From a224aced85421271b5138766e9843979bc6d34d5 Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Sat, 23 Aug 2025 13:04:09 +0000 Subject: [PATCH] refactor(cursor-rules): restructure rules architecture with meta-rule system - Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories --- .cursor/rules/README.md | 146 ++ .../app/architectural_decision_record.mdc | 297 +-- .cursor/rules/app/architectural_examples.mdc | 246 ++ .../app/architectural_implementation.mdc | 139 ++ .cursor/rules/app/architectural_patterns.mdc | 214 ++ .cursor/rules/app/timesafari.mdc | 316 +-- .cursor/rules/app/timesafari_development.mdc | 174 ++ .cursor/rules/app/timesafari_platforms.mdc | 167 ++ .../architecture/build_architecture_guard.mdc | 355 +-- .cursor/rules/architecture/build_testing.mdc | 248 ++ .../rules/architecture/build_validation.mdc | 224 ++ .cursor/rules/{ => core}/base_context.mdc | 79 +- .cursor/rules/core/harbor_pilot_universal.mdc | 224 ++ .cursor/rules/core/less_complex.mdc | 99 + .cursor/rules/database/absurd-sql.mdc | 88 +- .cursor/rules/database/legacy_dexie.mdc | 66 +- .../{ => development}/asset_configuration.mdc | 46 +- .../development/complexity_assessment.mdc | 177 ++ .../development/dependency_management.mdc | 177 ++ .../rules/development/development_guide.mdc | 26 +- .../historical_comment_management.mdc | 119 + .../historical_comment_patterns.mdc | 139 ++ .../investigation_report_example.mdc | 61 + .../rules/development/logging_migration.mdc | 358 +++ .../{ => development}/logging_standards.mdc | 166 +- .../rules/development/planning_examples.mdc | 160 ++ .../development/realistic_time_estimation.mdc | 128 + .../{ => development}/research_diagnostic.mdc | 104 +- .../software_development.mdc | 166 +- .cursor/rules/development/time.mdc | 146 ++ .cursor/rules/development/time_examples.mdc | 243 ++ .../time_implementation.mdc} | 224 +- .../rules/development/type_safety_guide.mdc | 97 +- .cursor/rules/docs/documentation.mdc | 33 +- .cursor/rules/docs/markdown-automation.mdc | 79 - .cursor/rules/docs/markdown.mdc | 366 --- .cursor/rules/docs/markdown_core.mdc | 175 ++ .cursor/rules/docs/markdown_templates.mdc | 219 ++ .cursor/rules/docs/markdown_workflow.mdc | 168 ++ .../rules/features/camera-implementation.mdc | 163 +- .cursor/rules/features/camera_platforms.mdc | 225 ++ .cursor/rules/features/camera_technical.mdc | 203 ++ .cursor/rules/harbor_pilot_universal.mdc | 206 -- .../rules/historical_comment_management.mdc | 236 -- .cursor/rules/less_complex.mdc | 49 - .cursor/rules/meta_bug_diagnosis.mdc | 172 ++ .cursor/rules/meta_bug_fixing.mdc | 175 ++ .cursor/rules/meta_core_always_on.mdc | 196 ++ .cursor/rules/meta_feature_implementation.mdc | 187 ++ .cursor/rules/meta_feature_planning.mdc | 165 ++ .cursor/rules/meta_research.mdc | 247 ++ .cursor/rules/meta_rule_architecture.md | 103 + .cursor/rules/realistic_time_estimation.mdc | 348 --- .../rules/{ => templates}/adr_template.mdc | 47 +- .cursor/rules/workflow/commit_messages.mdc | 196 ++ .cursor/rules/workflow/version_control.mdc | 321 +-- .cursor/rules/workflow/version_sync.mdc | 176 ++ .markdownlint-cli2.jsonc | 53 + .markdownlint.json | 28 +- package-lock.json | 2130 ++++++++++++++--- package.json | 22 +- 61 files changed, 9202 insertions(+), 3105 deletions(-) create mode 100644 .cursor/rules/README.md create mode 100644 .cursor/rules/app/architectural_examples.mdc create mode 100644 .cursor/rules/app/architectural_implementation.mdc create mode 100644 .cursor/rules/app/architectural_patterns.mdc create mode 100644 .cursor/rules/app/timesafari_development.mdc create mode 100644 .cursor/rules/app/timesafari_platforms.mdc create mode 100644 .cursor/rules/architecture/build_testing.mdc create mode 100644 .cursor/rules/architecture/build_validation.mdc rename .cursor/rules/{ => core}/base_context.mdc (78%) create mode 100644 .cursor/rules/core/harbor_pilot_universal.mdc create mode 100644 .cursor/rules/core/less_complex.mdc rename .cursor/rules/{ => development}/asset_configuration.mdc (62%) create mode 100644 .cursor/rules/development/complexity_assessment.mdc create mode 100644 .cursor/rules/development/dependency_management.mdc create mode 100644 .cursor/rules/development/historical_comment_management.mdc create mode 100644 .cursor/rules/development/historical_comment_patterns.mdc rename .cursor/rules/{ => development}/investigation_report_example.mdc (78%) create mode 100644 .cursor/rules/development/logging_migration.mdc rename .cursor/rules/{ => development}/logging_standards.mdc (52%) create mode 100644 .cursor/rules/development/planning_examples.mdc create mode 100644 .cursor/rules/development/realistic_time_estimation.mdc rename .cursor/rules/{ => development}/research_diagnostic.mdc (72%) rename .cursor/rules/{ => development}/software_development.mdc (53%) create mode 100644 .cursor/rules/development/time.mdc create mode 100644 .cursor/rules/development/time_examples.mdc rename .cursor/rules/{time.mdc => development/time_implementation.mdc} (54%) delete mode 100644 .cursor/rules/docs/markdown-automation.mdc delete mode 100644 .cursor/rules/docs/markdown.mdc create mode 100644 .cursor/rules/docs/markdown_core.mdc create mode 100644 .cursor/rules/docs/markdown_templates.mdc create mode 100644 .cursor/rules/docs/markdown_workflow.mdc create mode 100644 .cursor/rules/features/camera_platforms.mdc create mode 100644 .cursor/rules/features/camera_technical.mdc delete mode 100644 .cursor/rules/harbor_pilot_universal.mdc delete mode 100644 .cursor/rules/historical_comment_management.mdc delete mode 100644 .cursor/rules/less_complex.mdc create mode 100644 .cursor/rules/meta_bug_diagnosis.mdc create mode 100644 .cursor/rules/meta_bug_fixing.mdc create mode 100644 .cursor/rules/meta_core_always_on.mdc create mode 100644 .cursor/rules/meta_feature_implementation.mdc create mode 100644 .cursor/rules/meta_feature_planning.mdc create mode 100644 .cursor/rules/meta_research.mdc create mode 100644 .cursor/rules/meta_rule_architecture.md delete mode 100644 .cursor/rules/realistic_time_estimation.mdc rename .cursor/rules/{ => templates}/adr_template.mdc (59%) create mode 100644 .cursor/rules/workflow/commit_messages.mdc create mode 100644 .cursor/rules/workflow/version_sync.mdc create mode 100644 .markdownlint-cli2.jsonc diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 00000000..7f2762ad --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,146 @@ +# .cursor Rules Organization + +This directory contains all the rules and guidelines for AI assistants working +with the TimeSafari project. + +## Directory Structure + +### **`core/`** - Core Principles and Context + +Core rules that apply to all AI interactions and provide fundamental context. + +- **`base_context.mdc`** - Human competence first principles and interaction guidelines +- **`harbor_pilot_universal.mdc`** - Technical guide creation and investigation rules +- **`less_complex.mdc`** - Minimalist solution principle and complexity guidelines + +### **`development/`** - Development Practices and Standards + +Rules for software development, coding standards, and development workflows. + +- **`software_development.mdc`** - Core development principles and evidence requirements +- **`type_safety_guide.mdc`** - TypeScript type safety guidelines and best practices +- **`development_guide.mdc`** - Development environment setup and standards +- **`logging_standards.mdc`** - Logging implementation standards and rules +- **`logging_migration.mdc`** - Migration from console.* to structured logging +- **`time.mdc`** - Time handling principles and UTC standards +- **`time_examples.mdc`** - Practical time implementation examples +- **`time_implementation.mdc`** - Detailed time implementation guidelines +- **`realistic_time_estimation.mdc`** - Time estimation framework and principles +- **`planning_examples.mdc`** - Planning examples and best practices +- **`complexity_assessment.mdc`** - Complexity evaluation and assessment +- **`dependency_management.mdc`** - Dependency management and version control +- **`asset_configuration.mdc`** - Asset configuration and build integration +- **`research_diagnostic.mdc`** - Research and investigation workflows +- **`investigation_report_example.mdc`** - Investigation report templates and examples +- **`historical_comment_management.mdc`** - Historical comment transformation rules +- **`historical_comment_patterns.mdc`** - Comment transformation patterns and examples + +### **`architecture/`** - Architecture and Design Patterns + +Rules for architectural decisions, patterns, and system design. + +- **`build_architecture_guard.mdc`** - Build system protection and change levels +- **`build_validation.mdc`** - Build validation procedures and testing +- **`build_testing.mdc`** - Build testing requirements and feedback collection + +### **`app/`** - Application-Specific Rules + +Rules specific to the TimeSafari application and its architecture. + +- **`timesafari.mdc`** - Core application context and principles +- **`timesafari_platforms.mdc`** - Platform-specific implementation guidelines +- **`timesafari_development.mdc`** - TimeSafari development workflow +- **`architectural_decision_record.mdc`** - ADR creation and management +- **`architectural_implementation.mdc`** - Architecture implementation guidelines +- **`architectural_patterns.mdc`** - Architectural patterns and examples +- **`architectural_examples.mdc`** - Architecture examples and testing + +### **`database/`** - Database and Data Management + +Rules for database operations, migrations, and data handling. + +- **`absurd-sql.mdc`** - Absurd SQL implementation and worker thread setup +- **`legacy_dexie.mdc`** - Legacy Dexie migration guidelines + +### **`workflow/`** - Process and Workflow Management + +Rules for development workflows, version control, and process management. + +- **`version_control.mdc`** - Version control principles and commit guidelines +- **`version_sync.mdc`** - Version synchronization and changelog management +- **`commit_messages.mdc`** - Commit message format and conventions + +### **`features/** - Feature-Specific Implementations + +Rules for implementing specific features across platforms. + +- **`camera-implementation.mdc`** - Camera feature implementation overview +- **`camera_technical.mdc`** - Technical camera implementation details +- **`camera_platforms.mdc`** - Platform-specific camera implementation + +### **`docs/`** - Documentation Standards + +Rules for creating and maintaining documentation. + +- **`markdown_core.mdc`** - Core markdown formatting standards +- **`markdown_templates.mdc`** - Document templates and examples +- **`markdown_workflow.mdc`** - Markdown validation and workflow +- **`documentation.mdc`** - Documentation generation principles + +### **`templates/`** - Templates and Examples + +Template files and examples for various documentation types. + +- **`adr_template.mdc`** - Architectural Decision Record template + +### **Meta-Rules** - Workflow Bundling + +High-level meta-rules that bundle related sub-rules for specific workflows. + +- **`meta_core_always_on.mdc`** - Core rules that apply to every single prompt +- **`meta_feature_planning.mdc`** - Feature planning workflow bundling +- **`meta_bug_diagnosis.mdc`** - Bug investigation workflow bundling +- **`meta_bug_fixing.mdc`** - Bug fix implementation workflow bundling +- **`meta_feature_implementation.mdc`** - Feature implementation workflow bundling + +## Usage Guidelines + +1. **Always-On Rules**: Start with `meta_core_always_on.mdc` for every + single prompt +2. **Core Rules**: Always apply rules from `core/` directory +3. **Context-Specific**: Use rules from appropriate subdirectories based on + your task +4. **Meta-Rules**: Use workflow-specific meta-rules for specialized tasks +5. **Cross-References**: All files contain updated cross-references to + reflect the new structure +6. **Validation**: All files pass markdown validation and maintain + consistent formatting + +## Benefits of New Organization + +1. **Logical grouping** - Related rules are now co-located +2. **Easier navigation** - Developers can quickly find relevant rules +3. **Better maintainability** - Clear separation of concerns +4. **Scalable structure** - Easy to add new rules in appropriate categories +5. **Consistent cross-references** - All file links updated and working +6. **Workflow bundling** - Meta-rules provide high-level workflow guidance +7. **Feedback integration** - Built-in feedback mechanisms for continuous improvement + +## File Naming Convention + +- **Lowercase with underscores**: `file_name.mdc` +- **Descriptive names**: Names clearly indicate the rule's purpose +- **Consistent extensions**: All files use `.mdc` extension + +## Maintenance + +- **Cross-references**: Update when moving files between directories +- **Markdown validation**: Run `npm run markdown:check` after any changes +- **Organization**: Keep related rules in appropriate subdirectories +- **Documentation**: Update this README when adding new rules or directories + +--- + +**Status**: Active organization structure +**Last Updated**: 2025-08-21 +**Maintainer**: Development team diff --git a/.cursor/rules/app/architectural_decision_record.mdc b/.cursor/rules/app/architectural_decision_record.mdc index 91cd8e8d..c5622722 100644 --- a/.cursor/rules/app/architectural_decision_record.mdc +++ b/.cursor/rules/app/architectural_decision_record.mdc @@ -1,7 +1,3 @@ ---- -description: when you need to understand the system architecture or make changes that impact the system architecture -alwaysApply: false ---- # TimeSafari Cross-Platform Architecture Guide **Author**: Matthew Raymer @@ -12,17 +8,20 @@ alwaysApply: false | Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) | |---------|-----------|--------------------|-------------------| -| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented | +| 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 | +| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env + checks | ## 2. Project Structure ### Core Directories ``` + src/ ├── components/ # Vue components ├── services/ # Platform services and business logic @@ -37,14 +36,19 @@ src/ ├── 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 @@ -52,16 +56,18 @@ src/ ### Service Organization ```tree + services/ -├── QRScanner/ +├── QRScanner/ │ ├── WebInlineQRScanner.ts │ └── interfaces.ts -├── platforms/ +├── platforms/ │ ├── WebPlatformService.ts │ ├── CapacitorPlatformService.ts │ └── ElectronPlatformService.ts -└── factory/ +└── factory/ └── PlatformServiceFactory.ts + ``` ### Factory Pattern @@ -74,279 +80,114 @@ Use a **singleton factory** to select platform services via ### 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"); - ``` +- **Unit Tests**: Jest for business logic and utilities -> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15 -> min) with QA to align on coverage and flaky test risks. +- **E2E Tests**: Playwright for critical user journeys -## 7. Error Handling +- **Platform Tests**: Test platform-specific implementations -- 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`). +- **Integration Tests**: Test service interactions -## 8. Best Practices +## 7. Key Principles -- 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). +### Platform Independence -## 9. Dependency Management +- **Abstract platform differences** behind interfaces -- Key deps: `@capacitor/core`, `electron`, `vue`. -- Use conditional `import()` for platform-specific libs. +- **Use factory pattern** for service selection -## 10. Security Considerations +- **Maintain consistent APIs** across platforms -- **Permissions**: Always check + request gracefully. -- **Storage**: Secure storage for sensitive data; encrypt when possible. -- **Audits**: Schedule quarterly security reviews. +- **Graceful degradation** when features unavailable -## 11. ADR Process +### Code Organization -- All major architecture choices → log in `doc/adr/`. -- Use ADR template with Context, Decision, Consequences, Status. -- Link related ADRs in PR descriptions. +- **Single responsibility** for each service -> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min -> design sync for discussion, not just async review. +- **Interface segregation** for platform services -## 12. Collaboration Hooks +- **Dependency injection** via mixins -- **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? +- **Composition over inheritance** --- -**Status**: Active architecture guidelines -**Priority**: High -**Estimated Effort**: Ongoing reference -**Dependencies**: Vue 3, Capacitor, Electron, Vite -**Stakeholders**: Development team, Architecture team - -- [ ] 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? -# TimeSafari Cross-Platform Architecture Guide - -**Author**: Matthew Raymer -**Date**: 2025-08-19 -**Status**: 🎯 **ACTIVE** - Architecture guidelines - -## 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"); - ``` +**See also**: -> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15 -> min) with QA to align on coverage and flaky test risks. +- `.cursor/rules/app/architectural_implementation.mdc` for -## 7. Error Handling + detailed implementation details -- 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`). +- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and -## 8. Best Practices + examples -- 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. +**Status**: Active architecture guidelines +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: timesafari.mdc +**Stakeholders**: Development team, Architecture team -## 11. ADR Process +- [ ] Have relevant ADRs been updated/linked? -- All major architecture choices → log in `doc/adr/`. -- Use ADR template with Context, Decision, Consequences, Status. -- Link related ADRs in PR descriptions. +- [ ] Did I add competence hooks or prompts for the team? -> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min -> design sync for discussion, not just async review. +- [ ] Was human interaction (sync/review/demo) scheduled? -## 12. Collaboration Hooks +## Model Implementation Checklist -- **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. +### Before Architectural Decisions -## Self-Check +- [ ] **Decision Context**: Understand the architectural challenge to be addressed +- [ ] **Stakeholder Identification**: Identify all decision makers and affected parties +- [ ] **Research**: Research alternatives and gather evidence +- [ ] **Impact Assessment**: Assess impact on existing architecture -- [ ] 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? +### During Architectural Decisions ---- +- [ ] **Context Documentation**: Document the context and forces at play +- [ ] **Decision Recording**: Record the decision and rationale clearly +- [ ] **Consequences Analysis**: Analyze positive, negative, and neutral consequences +- [ ] **Alternatives Documentation**: Document alternatives considered and why rejected -**Status**: Active architecture guidelines -**Priority**: High -**Estimated Effort**: Ongoing reference -**Dependencies**: Vue 3, Capacitor, Electron, Vite -**Stakeholders**: Development team, Architecture team +### After Architectural Decisions -- [ ] 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? +- [ ] **ADR Creation**: Create or update Architectural Decision Record +- [ ] **Team Communication**: Communicate decision to all stakeholders +- [ ] **Implementation Planning**: Plan implementation of the architectural decision +- [ ] **Documentation Update**: Update relevant architectural documentation diff --git a/.cursor/rules/app/architectural_examples.mdc b/.cursor/rules/app/architectural_examples.mdc new file mode 100644 index 00000000..babc8e1a --- /dev/null +++ b/.cursor/rules/app/architectural_examples.mdc @@ -0,0 +1,246 @@ +# Time Safari Architecture — Examples and Testing + +> **Agent role**: Reference this file for architectural examples and + testing patterns when working with TimeSafari architecture. + +## Error Handling Patterns + +### Global Error Handler + +```typescript + +// main.ts +app.config.errorHandler = (err, instance, info) => { + const componentName = instance?.$options?.name || 'Unknown'; + logger.error(`[${componentName}] Vue error`, err, info); +}; + +window.addEventListener('unhandledrejection', (event) => { + logger.error('[Global] Unhandled promise rejection', event.reason); +}); + +``` + +### Platform-Specific Error Wrapping + +```typescript + +// services/platforms/CapacitorPlatformService.ts +export class CapacitorPlatformService { + async getFileContents(path: string): Promise { + try { + const result = await Filesystem.readFile({ + path: path, + encoding: 'utf8' + }); + return result.data; + } catch (error) { + logger.error('[Capacitor API Error] Failed to read file', error, path); + throw new Error(`Failed to read file: ${path}`); + } + } +} + +``` + +## Testing Patterns + +### Platform-Specific Test Skipping + +```typescript + +// tests/QRScanner.test.ts +describe('QRScanner Service', () => { + test('should start scanning on web', async () => { + test.skip(process.env.VITE_PLATFORM !== 'web', 'Web-only test'); + + const scanner = new WebInlineQRScanner(); + await scanner.startScanning(); + // Assert scanning started + }); + + test('should start scanning on mobile', async () => { + test.skip(process.env.VITE_PLATFORM !== 'capacitor', 'Mobile-only test'); + + const scanner = new CapacitorQRScanner(); + await scanner.startScanning(); + // Assert scanning started + }); +}); + +``` + +### Mock Service Testing + +```typescript + +// tests/mocks/QRScannerMock.ts +export class QRScannerMock implements QRScannerService { + private isScanning = false; + private listeners: Map = new Map(); + + async startScanning(): Promise { + this.isScanning = true; + this.emit('scanningStarted'); + } + + async stopScanning(): Promise { + this.isScanning = false; + this.emit('scanningStopped'); + } + + addListener(event: string, callback: Function): void { + if (!this.listeners.has(event)) { + this.listeners.set(event, []); + } + this.listeners.get(event)!.push(callback); + } + + removeListener(event: string, callback: Function): void { + const callbacks = this.listeners.get(event); + if (callbacks) { + const index = callbacks.indexOf(callback); + if (index > -1) { + callbacks.splice(index, 1); + } + } + } + + private emit(event: string, ...args: any[]): void { + const callbacks = this.listeners.get(event); + if (callbacks) { + callbacks.forEach(callback => callback(...args)); + } + } + + getScanningState(): boolean { + return this.isScanning; + } +} + +``` + +## Integration Examples + +### Service Composition + +```typescript + +// services/QRScannerService.ts +export class QRScannerService { + constructor( + private platformService: PlatformService, + private notificationService: NotificationService + ) {} + + async startScanning(): Promise { + try { + await this.platformService.startCamera(); + this.notificationService.show('Camera started'); + } catch (error) { + this.notificationService.showError('Failed to start camera'); + throw error; + } + } +} + +``` + +### Component Integration + +```typescript + +// components/QRScannerDialog.vue +export default class QRScannerDialog extends Vue { + @Inject() private qrScannerService!: QRScannerService; + + async mounted() { + try { + await this.qrScannerService.startScanning(); + } catch (error) { + this.$notify.error('Failed to start scanner'); + } + } + + beforeDestroy() { + this.qrScannerService.stopScanning(); + } +} + +``` + +## Best Practices + +### Service Design + +- Keep services focused and single-purpose + +- Use dependency injection for service composition + +- Implement proper error handling and logging + +- Provide clear interfaces and contracts + +### Testing Strategy + +- Test platform-specific behavior separately + +- Use mocks for external dependencies + +- Test error conditions and edge cases + +- Validate service contracts and interfaces + +### Error Handling + +- Log errors with appropriate context + +- Provide user-friendly error messages + +- Implement graceful degradation + +- Handle platform-specific error scenarios + +--- + +**See also**: + +- `.cursor/rules/app/architectural_decision_record.mdc` for + + core architecture principles + +- `.cursor/rules/app/architectural_implementation.mdc` for + + implementation details + +- `.cursor/rules/app/architectural_patterns.mdc` for core patterns + +**Status**: Active examples and testing guide +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: architectural_patterns.mdc +**Stakeholders**: Development team, Testing team + +## Model Implementation Checklist + +### Before Architectural Examples + +- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use + case +- [ ] **Service Design**: Plan service structure and dependencies +- [ ] **Testing Strategy**: Plan testing approach for the example +- [ ] **Error Handling**: Plan error handling and logging strategy + +### During Architectural Examples + +- [ ] **Service Implementation**: Implement focused, single-purpose services +- [ ] **Dependency Injection**: Use proper dependency injection patterns +- [ ] **Error Handling**: Implement proper error handling and logging +- [ ] **Interface Design**: Provide clear interfaces and contracts + +### After Architectural Examples + +- [ ] **Testing Execution**: Test platform-specific behavior separately +- [ ] **Service Validation**: Validate service contracts and interfaces +- [ ] **Error Testing**: Test error conditions and edge cases +- [ ] **Documentation**: Update architectural examples documentation diff --git a/.cursor/rules/app/architectural_implementation.mdc b/.cursor/rules/app/architectural_implementation.mdc new file mode 100644 index 00000000..bd853860 --- /dev/null +++ b/.cursor/rules/app/architectural_implementation.mdc @@ -0,0 +1,139 @@ +# Time Safari Architecture — Implementation Details + +> **Agent role**: Reference this file for detailed implementation details when + working with TimeSafari architecture implementation. + +## 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`). + +## 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). + +## Dependency Management + +- Key deps: `@capacitor/core`, `electron`, `vue`. + +- Use conditional `import()` for platform-specific libs. + +## Security Considerations + +- **Permissions**: Always check + request gracefully. + +- **Storage**: Secure storage for sensitive data; encrypt when possible. + +- **Audits**: Schedule quarterly security reviews. + +## 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. + +## 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. + +## Testing Implementation + +- **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. + +## 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? + +--- + +**See also**: + +- `.cursor/rules/app/architectural_decision_record.mdc` for + + core architecture principles + +- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and + + examples + +**Status**: Active implementation guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: architectural_decision_record.mdc +**Stakeholders**: Development team, Architecture team + +## Model Implementation Checklist + +### Before Architectural Implementation + +- [ ] **Interface Review**: Verify feature implements shared interface +- [ ] **ADR Review**: Check if ADR is required for major changes +- [ ] **Security Assessment**: Assess security implications for QR features +- [ ] **Platform Planning**: Plan platform-specific implementation details + +### During Architectural Implementation + +- [ ] **Interface Implementation**: Implement shared interfaces consistently +- [ ] **Error Handling**: Implement graceful fallbacks and error handling +- [ ] **Testing Strategy**: Plan unit tests for services and E2E tests +- [ ] **Human Interaction**: Schedule syncs/reviews/demos as needed + +### After Architectural Implementation + +- [ ] **Interface Validation**: Verify shared interfaces are properly implemented +- [ ] **Testing Execution**: Run unit tests and platform-specific tests +- [ ] **ADR Updates**: Update relevant ADRs and link in PR descriptions +- [ ] **Team Communication**: Share implementation results with team diff --git a/.cursor/rules/app/architectural_patterns.mdc b/.cursor/rules/app/architectural_patterns.mdc new file mode 100644 index 00000000..026a8354 --- /dev/null +++ b/.cursor/rules/app/architectural_patterns.mdc @@ -0,0 +1,214 @@ +# Time Safari Architecture — Patterns and Examples + +> **Agent role**: Reference this file for architectural patterns and +> examples when working with TimeSafari architecture design. + +## Architectural Patterns + +### Factory Pattern Implementation + +```typescript +// PlatformServiceFactory.ts +export class PlatformServiceFactory { + private static instance: PlatformServiceFactory; + + static getInstance(): PlatformServiceFactory { + if (!PlatformServiceFactory.instance) { + PlatformServiceFactory.instance = new PlatformServiceFactory(); + } + return PlatformServiceFactory.instance; + } + + getQRScannerService(): QRScannerService { + const platform = process.env.VITE_PLATFORM; + + switch (platform) { + case 'web': + return new WebInlineQRScanner(); + case 'capacitor': + return new CapacitorQRScanner(); + case 'electron': + return new ElectronQRScanner(); + default: + throw new Error(`Unsupported platform: ${platform}`); + } + } +} +``` + +### Service Interface Definition + +```typescript +// interfaces/QRScannerService.ts +export interface QRScannerService { + startScanning(): Promise; + stopScanning(): Promise; + addListener(event: string, callback: Function): void; + removeListener(event: string, callback: Function): void; +} +``` + +### Platform-Specific Implementation + +```typescript +// services/QRScanner/WebInlineQRScanner.ts +export class WebInlineQRScanner implements QRScannerService { + private listeners: Map = new Map(); + + async startScanning(): Promise { + // Web-specific implementation + const stream = await navigator.mediaDevices.getUserMedia({ video: true }); + // Process video stream for QR codes + } + + async stopScanning(): Promise { + // Stop video stream + } + + addListener(event: string, callback: Function): void { + if (!this.listeners.has(event)) { + this.listeners.set(event, []); + } + this.listeners.get(event)!.push(callback); + } + + removeListener(event: string, callback: Function): void { + const callbacks = this.listeners.get(event); + if (callbacks) { + const index = callbacks.indexOf(callback); + if (index > -1) { + callbacks.splice(index, 1); + } + } + } +} +``` + +## Deep Linking Implementation + +### URL Format + +``` +timesafari://[/][?query=value] +``` + +### Web Implementation + +```typescript +// router/index.ts +router.beforeEach((to, from, next) => { + // Parse deep link parameters + if (to.query.deepLink) { + const deepLink = to.query.deepLink as string; + // Process deep link + handleDeepLink(deepLink); + } + next(); +}); + +function handleDeepLink(deepLink: string) { + // Parse and route deep link + const url = new URL(deepLink); + const route = url.pathname; + const params = url.searchParams; + + // Navigate to appropriate route + router.push({ name: route, query: Object.fromEntries(params) }); +} +``` + +### Capacitor Implementation + +```typescript +// main.capacitor.ts +import { App } from '@capacitor/app'; + +App.addListener('appUrlOpen', (data) => { + const url = data.url; + // Parse deep link and navigate + handleDeepLink(url); +}); +``` + +## Platform Detection + +### Feature Detection vs Platform Detection + +```typescript +// ✅ Good: Feature detection +function hasCameraAccess(): boolean { + return 'mediaDevices' in navigator && + 'getUserMedia' in navigator.mediaDevices; +} + +// ❌ Bad: Platform detection +function isWeb(): boolean { + return process.env.VITE_PLATFORM === 'web'; +} +``` + +### Conditional Imports + +```typescript +// services/platforms/index.ts +export async function getPlatformService() { + const platform = process.env.VITE_PLATFORM; + + switch (platform) { + case 'capacitor': + const { CapacitorPlatformService } = + await import('./CapacitorPlatformService'); + return new CapacitorPlatformService(); + case 'electron': + const { ElectronPlatformService } = + await import('./ElectronPlatformService'); + return new ElectronPlatformService(); + default: + const { WebPlatformService } = + await import('./WebPlatformService'); + return new WebPlatformService(); + } +} +``` + +--- + +**See also**: + +- `.cursor/rules/app/architectural_decision_record.mdc` for core + architecture principles +- `.cursor/rules/app/architectural_implementation.mdc` for + implementation details +- `.cursor/rules/app/architectural_examples.mdc` for examples and + testing patterns + +**Status**: Active patterns and examples +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: architectural_decision_record.mdc, + architectural_implementation.mdc +**Stakeholders**: Development team, Architecture team + +## Model Implementation Checklist + +### Before Architectural Patterns + +- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use + case +- [ ] **Platform Analysis**: Identify platform-specific requirements +- [ ] **Service Planning**: Plan service structure and dependencies +- [ ] **Testing Strategy**: Plan testing approach for the pattern + +### During Architectural Patterns + +- [ ] **Pattern Implementation**: Implement chosen architectural pattern +- [ ] **Platform Abstraction**: Use platform abstraction layers appropriately +- [ ] **Service Composition**: Compose services using dependency injection +- [ ] **Interface Design**: Provide clear interfaces and contracts + +### After Architectural Patterns + +- [ ] **Pattern Validation**: Verify pattern is implemented correctly +- [ ] **Platform Testing**: Test across all target platforms +- [ ] **Service Testing**: Test service composition and dependencies +- [ ] **Documentation**: Update architectural patterns documentation diff --git a/.cursor/rules/app/timesafari.mdc b/.cursor/rules/app/timesafari.mdc index 513954c0..ad8a2249 100644 --- a/.cursor/rules/app/timesafari.mdc +++ b/.cursor/rules/app/timesafari.mdc @@ -1,5 +1,5 @@ --- -alwaysApply: true +alwaysApply: false --- # Time Safari Context @@ -18,191 +18,12 @@ that preserve privacy and data sovereignty. ## Core Goals 1. **Connect**: Make it easy, rewarding, and non-threatening for people to - connect with others who have similar interests, and to initiate activities - together. - -2. **Reveal**: Widely advertise the great support and rewards that are being - given and accepted freely, especially non-monetary ones, showing the impact - gifts make in people's lives. - -## Technical Foundation - -### Architecture - -- **Privacy-preserving claims architecture** via endorser.ch -- **Decentralized Identifiers (DIDs)**: User identities based on - public/private key pairs stored on devices -- **Cryptographic Verification**: All claims and confirmations are - cryptographically signed -- **User-Controlled Visibility**: Users explicitly control who can see their - identifiers and data -- **Cross-Platform**: Web (PWA), Mobile (Capacitor), Desktop (Electron) - -### Current Database State - -- **Database**: SQLite via Absurd SQL (browser) and native SQLite - (mobile/desktop) -- **Legacy Support**: IndexedDB (Dexie) for backward compatibility -- **Status**: Modern database architecture fully implemented - -### Core Technologies - -- **Frontend**: Vue 3 + TypeScript + vue-facing-decorator -- **Styling**: TailwindCSS -- **Build**: Vite with platform-specific configs -- **Testing**: Playwright E2E, Jest unit tests -- **Database**: SQLite (Absurd SQL in browser), IndexedDB (legacy) -- **State**: Pinia stores -- **Platform Services**: Abstracted behind interfaces with factory pattern - -## Development Principles - -### Code Organization - -- **Platform Services**: Abstract platform-specific code behind interfaces -- **Service Factory**: Use `PlatformServiceFactory` for platform selection -- **Type Safety**: Strict TypeScript, no `any` types, use type guards -- **Modern Architecture**: Use current platform service patterns - -### Architecture Patterns - -- **Dependency Injection**: Services injected via mixins and factory pattern -- **Interface Segregation**: Small, focused interfaces over large ones -- **Composition over Inheritance**: Prefer mixins and composition -- **Single Responsibility**: Each component/service has one clear purpose - -### Testing Strategy - -- **E2E**: Playwright for critical user journeys -- **Unit**: Jest with F.I.R.S.T. principles -- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI -- **Quality Assurance**: Comprehensive testing and validation - -## Current Development Focus - -### Active Development - -- **Feature Development**: Build new functionality using modern platform - services -- **Performance Optimization**: Improve app performance and user experience -- **Platform Enhancement**: Leverage platform-specific capabilities -- **Code Quality**: Maintain high standards and best practices - -### Development Metrics - -- **Code Quality**: High standards maintained across all platforms -- **Performance**: Optimized for all target devices -- **Testing**: Comprehensive coverage maintained -- **User Experience**: Focus on intuitive, accessible interfaces - -## Platform-Specific Considerations - -### Web (PWA) - -- **QR Scanning**: WebInlineQRScanner -- **Deep Linking**: URL parameters -- **File System**: Limited browser APIs -- **Build**: `npm run build:web` (development build) - -### Mobile (Capacitor) - -- **QR Scanning**: @capacitor-mlkit/barcode-scanning -- **Deep Linking**: App URL open events -- **File System**: Capacitor Filesystem -- **Build**: `npm run build:capacitor` - -### Desktop (Electron) - -- **File System**: Node.js fs -- **Build**: `npm run build:electron` -- **Distribution**: AppImage, DEB, DMG packages - -## Development Workflow - -### Build Commands -```bash -# Web (development) -npm run build:web - -# Mobile -npm run build:capacitor -npm run build:native - -# Desktop -npm run build:electron -npm run build:electron:appimage -npm run build:electron:deb -npm run build:electron:dmg -``` - -### Testing Commands - -```bash -# Web E2E -npm run test:web - -# Mobile -npm run test:mobile -npm run test:android -npm run test:ios - -# Type checking -npm run type-check -npm run lint-fix -``` - -## Key Constraints - -1. **Privacy First**: User identifiers remain private except when explicitly - shared -2. **Platform Compatibility**: Features must work across all target platforms -3. **Performance**: Must remain performant on older/simpler devices -4. **Modern Architecture**: New features should use current platform services -5. **Offline Capability**: Key functionality should work offline when feasible - -## Use Cases to Support - -1. **Community Building**: Tools for finding others with shared interests -2. **Project Coordination**: Easy proposal and collaboration on projects -3. **Reputation Building**: Showcasing contributions and reliability -4. **Governance**: Facilitating decision-making and collective governance - -## Resources - -- **Testing**: `docs/migration-testing/` -- **Architecture**: `docs/architecture-decisions.md` -- **Build Context**: `docs/build-modernization-context.md` - ---- - -## Status: Active application context - -- **Priority**: Critical -- **Estimated Effort**: Ongoing reference -- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron -- **Stakeholders**: Development team, Product team -# Time Safari Context - -**Author**: Matthew Raymer -**Date**: 2025-08-19 -**Status**: 🎯 **ACTIVE** - Core application context - -## Project Overview - -Time Safari is an application designed to foster community building through -gifts, gratitude, and collaborative projects. The app makes it easy and -intuitive for users of any age and capability to recognize contributions, -build trust networks, and organize collective action. It is built on services -that preserve privacy and data sovereignty. - -## Core Goals - -1. **Connect**: Make it easy, rewarding, and non-threatening for people to connect with others who have similar interests, and to initiate activities together. 2. **Reveal**: Widely advertise the great support and rewards that are being + given and accepted freely, especially non-monetary ones, showing the impact gifts make in people's lives. @@ -211,29 +32,45 @@ that preserve privacy and data sovereignty. ### Architecture - **Privacy-preserving claims architecture** via endorser.ch + - **Decentralized Identifiers (DIDs)**: User identities based on + public/private key pairs stored on devices + - **Cryptographic Verification**: All claims and confirmations are + cryptographically signed + - **User-Controlled Visibility**: Users explicitly control who can see their + identifiers and data + - **Cross-Platform**: Web (PWA), Mobile (Capacitor), Desktop (Electron) ### Current Database State - **Database**: SQLite via Absurd SQL (browser) and native SQLite + (mobile/desktop) + - **Legacy Support**: IndexedDB (Dexie) for backward compatibility + - **Status**: Modern database architecture fully implemented ### Core Technologies - **Frontend**: Vue 3 + TypeScript + vue-facing-decorator + - **Styling**: TailwindCSS + - **Build**: Vite with platform-specific configs + - **Testing**: Playwright E2E, Jest unit tests + - **Database**: SQLite (Absurd SQL in browser), IndexedDB (legacy) + - **State**: Pinia stores + - **Platform Services**: Abstracted behind interfaces with factory pattern ## Development Principles @@ -241,22 +78,31 @@ that preserve privacy and data sovereignty. ### Code Organization - **Platform Services**: Abstract platform-specific code behind interfaces + - **Service Factory**: Use `PlatformServiceFactory` for platform selection + - **Type Safety**: Strict TypeScript, no `any` types, use type guards + - **Modern Architecture**: Use current platform service patterns ### Architecture Patterns - **Dependency Injection**: Services injected via mixins and factory pattern + - **Interface Segregation**: Small, focused interfaces over large ones + - **Composition over Inheritance**: Prefer mixins and composition + - **Single Responsibility**: Each component/service has one clear purpose ### Testing Strategy - **E2E**: Playwright for critical user journeys + - **Unit**: Jest with F.I.R.S.T. principles + - **Platform Coverage**: Web + Capacitor (Pixel 5) in CI + - **Quality Assurance**: Comprehensive testing and validation ## Current Development Focus @@ -264,102 +110,64 @@ that preserve privacy and data sovereignty. ### Active Development - **Feature Development**: Build new functionality using modern platform + services + - **Performance Optimization**: Improve app performance and user experience + - **Platform Enhancement**: Leverage platform-specific capabilities + - **Code Quality**: Maintain high standards and best practices ### Development Metrics - **Code Quality**: High standards maintained across all platforms -- **Performance**: Optimized for all target devices -- **Testing**: Comprehensive coverage maintained -- **User Experience**: Focus on intuitive, accessible interfaces - -## Platform-Specific Considerations - -### Web (PWA) - -- **QR Scanning**: WebInlineQRScanner -- **Deep Linking**: URL parameters -- **File System**: Limited browser APIs -- **Build**: `npm run build:web` (development build) - -### Mobile (Capacitor) - -- **QR Scanning**: @capacitor-mlkit/barcode-scanning -- **Deep Linking**: App URL open events -- **File System**: Capacitor Filesystem -- **Build**: `npm run build:capacitor` - -### Desktop (Electron) -- **File System**: Node.js fs -- **Build**: `npm run build:electron` -- **Distribution**: AppImage, DEB, DMG packages - -## Development Workflow +- **Performance**: Optimized for all target devices -### Build Commands +- **Testing**: Comprehensive coverage maintained -```bash -# Web (development) -npm run build:web +- **User Experience**: Focus on intuitive, accessible interfaces -# Mobile -npm run build:capacitor -npm run build:native +--- -# Desktop -npm run build:electron -npm run build:electron:appimage -npm run build:electron:deb -npm run build:electron:dmg -``` +**See also**: -### Testing Commands +- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details -```bash -# Web E2E -npm run test:web +- `.cursor/rules/app/timesafari_development.mdc` for -# Mobile -npm run test:mobile -npm run test:android -npm run test:ios + development workflow details -# Type checking -npm run type-check -npm run lint-fix -``` +**Status**: Active application context +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Product team -## Key Constraints +- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron -1. **Privacy First**: User identifiers remain private except when explicitly - shared -2. **Platform Compatibility**: Features must work across all target platforms -3. **Performance**: Must remain performant on older/simpler devices -4. **Modern Architecture**: New features should use current platform services -5. **Offline Capability**: Key functionality should work offline when feasible +- **Stakeholders**: Development team, Product team -## Use Cases to Support +## Model Implementation Checklist -1. **Community Building**: Tools for finding others with shared interests -2. **Project Coordination**: Easy proposal and collaboration on projects -3. **Reputation Building**: Showcasing contributions and reliability -4. **Governance**: Facilitating decision-making and collective governance +### Before TimeSafari Development -## Resources +- [ ] **Application Context**: Understand TimeSafari's community-building purpose +- [ ] **Platform Analysis**: Identify target platforms (web, mobile, desktop) +- [ ] **Architecture Review**: Review current platform service patterns +- [ ] **Testing Strategy**: Plan testing approach for all platforms -- **Testing**: `docs/migration-testing/` -- **Architecture**: `docs/architecture-decisions.md` -- **Build Context**: `docs/build-modernization-context.md` +### During TimeSafari Development ---- +- [ ] **Platform Services**: Use abstracted platform services via interfaces +- [ ] **Type Safety**: Implement strict TypeScript with type guards +- **Modern Architecture**: Follow current platform service patterns +- [ ] **Performance Focus**: Ensure performance on all target devices -## Status: Active application context +### After TimeSafari Development -- **Priority**: Critical -- **Estimated Effort**: Ongoing reference -- **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron -- **Stakeholders**: Development team, Product team +- [ ] **Cross-Platform Testing**: Test functionality across all platforms +- [ ] **Performance Validation**: Verify performance meets requirements +- [ ] **Code Quality**: Ensure high standards maintained +- [ ] **Documentation Update**: Update relevant documentation diff --git a/.cursor/rules/app/timesafari_development.mdc b/.cursor/rules/app/timesafari_development.mdc new file mode 100644 index 00000000..e72c68dc --- /dev/null +++ b/.cursor/rules/app/timesafari_development.mdc @@ -0,0 +1,174 @@ +# Time Safari Development — Workflow and Processes + +> **Agent role**: Reference this file for development workflow details when + working with TimeSafari development processes. + +## Development Workflow + +### Build Commands + +```bash + +# Web (development) + +npm run build:web + +# Mobile + +npm run build:capacitor +npm run build:native + +# Desktop + +npm run build:electron +npm run build:electron:appimage +npm run build:electron:deb +npm run build:electron:dmg + +``` + +### Testing Commands + +```bash + +# Web E2E + +npm run test:web + +# Mobile + +npm run test:mobile +npm run test:android +npm run test:ios + +# Type checking + +npm run type-check +npm run lint-fix + +``` + +## Development Principles + +### Code Organization + +- **Platform Services**: Abstract platform-specific code behind interfaces + +- **Service Factory**: Use `PlatformServiceFactory` for platform selection + +- **Type Safety**: Strict TypeScript, no `any` types, use type guards + +- **Modern Architecture**: Use current platform service patterns + +### Architecture Patterns + +- **Dependency Injection**: Services injected via mixins and factory pattern + +- **Interface Segregation**: Small, focused interfaces over large ones + +- **Composition over Inheritance**: Prefer mixins and composition + +- **Single Responsibility**: Each component/service has one clear purpose + +### Testing Strategy + +- **E2E**: Playwright for critical user journeys + +- **Unit**: Jest with F.I.R.S.T. principles + +- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI + +- **Quality Assurance**: Comprehensive testing and validation + +## Current Development Focus + +### Active Development + +- **Feature Development**: Build new functionality using modern platform + + services + +- **Performance Optimization**: Improve app performance and user experience + +- **Platform Enhancement**: Leverage platform-specific capabilities + +- **Code Quality**: Maintain high standards and best practices + +### Development Metrics + +- **Code Quality**: High standards maintained across all platforms + +- **Performance**: Optimized for all target devices + +- **Testing**: Comprehensive coverage maintained + +- **User Experience**: Focus on intuitive, accessible interfaces + +## Development Environment + +### Required Tools + +- **Node.js**: LTS version with npm + +- **Git**: Version control with proper branching strategy + +- **IDE**: VS Code with recommended extensions + +- **Platform Tools**: Android Studio, Xcode (for mobile development) + +### Environment Setup + +1. **Clone Repository**: `git clone ` + +2. **Install Dependencies**: `npm install` + +3. **Environment Variables**: Copy `.env.example` to `.env.local` + +4. **Platform Setup**: Follow platform-specific setup guides + +### Quality Assurance + +- **Linting**: ESLint with TypeScript rules + +- **Formatting**: Prettier for consistent code style + +- **Type Checking**: TypeScript strict mode enabled + +- **Testing**: Comprehensive test coverage requirements + +--- + +**See also**: + +- `.cursor/rules/app/timesafari.mdc` for core application context + +- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details + +**Status**: Active development workflow +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: timesafari.mdc, timesafari_platforms.mdc +**Stakeholders**: Development team, DevOps team + +## Model Implementation Checklist + +### Before TimeSafari Development + +- [ ] **Environment Setup**: Verify development environment is ready +- [ ] **Platform Tools**: Ensure platform-specific tools are available +- [ ] **Dependencies**: Check all required dependencies are installed +- [ ] **Environment Variables**: Configure local environment variables + +### During TimeSafari Development + +- [ ] **Platform Services**: Use modern platform service patterns +- [ ] **Code Quality**: Follow ESLint and TypeScript strict rules +- [ ] **Testing**: Implement comprehensive testing strategy +- [ ] **Performance**: Optimize for all target platforms + +### After TimeSafari Development + +- [ ] **Quality Checks**: Run linting, formatting, and type checking +- [ ] **Testing**: Execute comprehensive tests across platforms +- [ ] **Performance Validation**: Verify performance meets requirements +- [ ] **Documentation**: Update development documentation diff --git a/.cursor/rules/app/timesafari_platforms.mdc b/.cursor/rules/app/timesafari_platforms.mdc new file mode 100644 index 00000000..158e61f2 --- /dev/null +++ b/.cursor/rules/app/timesafari_platforms.mdc @@ -0,0 +1,167 @@ +# Time Safari Platforms — Platform-Specific Considerations + +> **Agent role**: Reference this file for platform-specific details when working + with TimeSafari development across different platforms. + +## Platform-Specific Considerations + +### Web (PWA) + +- **QR Scanning**: WebInlineQRScanner + +- **Deep Linking**: URL parameters + +- **File System**: Limited browser APIs + +- **Build**: `npm run build:web` (development build) + +### Mobile (Capacitor) + +- **QR Scanning**: @capacitor-mlkit/barcode-scanning + +- **Deep Linking**: App URL open events + +- **File System**: Capacitor Filesystem + +- **Build**: `npm run build:capacitor` + +### Desktop (Electron) + +- **File System**: Node.js fs + +- **Build**: `npm run build:electron` + +- **Distribution**: AppImage, DEB, DMG packages + +## Platform Compatibility Requirements + +### Cross-Platform Features + +- **Core functionality** must work identically across all platforms + +- **Platform-specific enhancements** should be additive, not required + +- **Fallback behavior** must be graceful when platform features unavailable + +### Platform-Specific Capabilities + +- **Web**: Browser APIs, PWA features, responsive design + +- **Mobile**: Native device features, offline capability, app store compliance + +- **Desktop**: File system access, system integration, native performance + +## Build and Distribution + +### Build Commands + +```bash + +# Web (development) + +npm run build:web + +# Mobile + +npm run build:capacitor +npm run build:native + +# Desktop + +npm run build:electron +npm run build:electron:appimage +npm run build:electron:deb +npm run build:electron:dmg + +``` + +### Testing Commands + +```bash + +# Web E2E + +npm run test:web + +# Mobile + +npm run test:mobile +npm run test:android +npm run test:ios + +# Type checking + +npm run type-check +npm run lint-fix + +``` + +## Key Constraints + +1. **Privacy First**: User identifiers remain private except when explicitly + + shared + +2. **Platform Compatibility**: Features must work across all target platforms + +3. **Performance**: Must remain performant on older/simpler devices + +4. **Modern Architecture**: New features should use current platform services + +5. **Offline Capability**: Key functionality should work offline when feasible + +## Use Cases to Support + +1. **Community Building**: Tools for finding others with shared interests + +2. **Project Coordination**: Easy proposal and collaboration on projects + +3. **Reputation Building**: Showcasing contributions and reliability + +4. **Governance**: Facilitating decision-making and collective governance + +## Resources + +- **Testing**: `docs/migration-testing/` + +- **Architecture**: `docs/architecture-decisions.md` + +- **Build Context**: `docs/build-modernization-context.md` + +--- + +**See also**: + +- `.cursor/rules/app/timesafari.mdc` for core application context +- `.cursor/rules/app/timesafari_development.mdc` for + + development workflow details + +**Status**: Active platform guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: timesafari.mdc +**Stakeholders**: Development team, Platform teams + +## Model Implementation Checklist + +### Before Platform Development + +- [ ] **Platform Analysis**: Identify all target platforms (web, mobile, desktop) +- [ ] **Feature Requirements**: Understand feature requirements across platforms +- [ ] **Platform Constraints**: Review platform-specific limitations and capabilities +- [ ] **Testing Strategy**: Plan testing approach for all target platforms + +### During Platform Development + +- [ ] **Cross-Platform Implementation**: Implement features across all platforms +- [ ] **Platform Services**: Use current platform services for new features +- [ ] **Performance Optimization**: Ensure performance on older/simpler devices +- [ ] **Offline Capability**: Implement offline functionality where feasible + +### After Platform Development + +- [ ] **Cross-Platform Testing**: Test functionality across all target platforms +- [ ] **Performance Validation**: Verify performance meets requirements +- [ ] **Documentation Update**: Update platform-specific documentation +- [ ] **Team Communication**: Share platform implementation results with team diff --git a/.cursor/rules/architecture/build_architecture_guard.mdc b/.cursor/rules/architecture/build_architecture_guard.mdc index dbd3cf76..1b07690b 100644 --- a/.cursor/rules/architecture/build_architecture_guard.mdc +++ b/.cursor/rules/architecture/build_architecture_guard.mdc @@ -1,8 +1,3 @@ ---- -description: Guards against unauthorized changes to the TimeSafari building - architecture -alwaysApply: false ---- # Build Architecture Guard Directive @@ -17,34 +12,57 @@ could break the multi-platform build pipeline, deployment processes, or development workflow. This directive ensures all build system modifications follow proper review, testing, and documentation procedures. -**Note**: Recent Android build system enhancements (2025-08-22) include sophisticated asset validation, platform-specific API routing, and automatic resource regeneration. These features require enhanced testing and validation procedures. +**Note**: Recent Android build system enhancements (2025-08-22) include + sophisticated asset validation, platform-specific API routing, and automatic + resource regeneration. These features require enhanced testing and validation + procedures. ## Protected Architecture Components ### Core Build Infrastructure - **Vite Configuration Files**: `vite.config.*.mts` files + - **Build Scripts**: All scripts in `scripts/` directory + - **Package Scripts**: `package.json` build-related scripts + - **Platform Configs**: `capacitor.config.ts`, `electron/`, `android/`, + `ios/` + - **Docker Configuration**: `Dockerfile`, `docker-compose.yml` + - **Environment Files**: `.env.*`, `.nvmrc`, `.node-version` ### Android-Specific Build Validation -- **Asset Validation Scripts**: `validate_android_assets()` function and resource checking +- **Asset Validation Scripts**: + + `validate_android_assets()` function and resource checking + - **Resource Generation**: `capacitor-assets` integration and verification -- **Platform-Specific IP Handling**: Android emulator vs physical device API routing + +- **Platform-Specific IP Handling**: + + Android emulator vs physical device API routing + - **Build Mode Validation**: Development/test/production mode handling -- **Resource Fallback Logic**: Automatic regeneration of missing Android resources + +- **Resource Fallback Logic**: + + Automatic regeneration of missing Android resources ### Critical Build Dependencies - **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode + - **Asset Management**: `capacitor-assets.config.json`, asset scripts + - **Testing Infrastructure**: Playwright, Jest, mobile test scripts + - **CI/CD Pipeline**: GitHub Actions, build validation scripts + - **Service Worker Assembly**: `sw_scripts/`, `sw_combine.js`, WASM copy steps ## Change Authorization Requirements @@ -52,8 +70,11 @@ follow proper review, testing, and documentation procedures. ### Level 1: Minor Changes (Requires Review) - Documentation updates to `BUILDING.md` + - Non-breaking script improvements + - Test additions or improvements + - Asset configuration updates **Process**: Code review + basic testing @@ -61,11 +82,21 @@ follow proper review, testing, and documentation procedures. ### Level 2: Moderate Changes (Requires Testing) - New build script additions + - Environment variable changes + - Dependency version updates + - Platform-specific optimizations -- **Build script argument parsing**: New flag handling (--api-ip, --auto-run, --deploy) -- **Platform-specific environment overrides**: Android API server IP customization + +- **Build script argument parsing**: + + New flag handling (--api-ip, --auto-run, --deploy) + +- **Platform-specific environment overrides**: + + Android API server IP customization + - **Asset regeneration logic**: Automatic fallback for missing Android resources **Process**: Code review + platform testing + documentation update @@ -73,8 +104,11 @@ follow proper review, testing, and documentation procedures. ### Level 3: Major Changes (Requires ADR) - Build system architecture changes + - New platform support + - Breaking changes to build scripts + - Major dependency migrations **Process**: ADR creation + comprehensive testing + team review @@ -84,290 +118,69 @@ follow proper review, testing, and documentation procedures. ### ❌ Never Allow Without ADR - **Delete or rename** core build scripts + - **Modify** `package.json` build script names + - **Change** Vite configuration structure + - **Remove** platform-specific build targets + - **Alter** Docker build process + - **Modify** CI/CD pipeline without testing ### ❌ Never Allow Without Testing - **Update** build dependencies -- **Change** environment configurations -- **Modify** asset generation scripts -- **Alter** test infrastructure -- **Update** platform SDK versions - -## Required Validation Checklist - -### Before Any Build System Change - -- [ ] **Impact Assessment**: Which platforms are affected? -- [ ] **Testing Plan**: How will this be tested across platforms? -- [ ] **Rollback Plan**: How can this be reverted if it breaks? -- [ ] **Documentation**: Will `BUILDING.md` need updates? -- [ ] **Dependencies**: Are all required tools available? - -### After Build System Change - -- [ ] **Web Platform**: Does `npm run build:web:dev` work? -- [ ] **Mobile Platforms**: Do iOS/Android builds succeed? -- [ ] **Desktop Platform**: Does Electron build and run? -- [ ] **Tests Pass**: Do all build-related tests pass? -- [ ] **Documentation Updated**: Is `BUILDING.md` current? - -## Specific Test Commands (Minimum Required) - -### Web Platform - -- **Development**: `npm run build:web:dev` - serve and load app -- **Production**: `npm run build:web:prod` - verify SW and WASM present - -### Mobile Platforms - -- **Android**: `npm run build:android:test` or `:prod` - confirm assets copied -- **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds - -### Android Platform (Enhanced) -- **Development Mode**: `npm run build:android --dev` - verify 10.0.2.2 API routing -- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` - verify custom IP -- **Asset Validation**: `npm run build:android --assets` - verify resource generation -- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment - -### Desktop Platform - -- **Electron**: `npm run build:electron:dev` and packaging for target OS -- **Verify**: Single-instance behavior and app boot - -### Auto-run (if affected) - -- **Test Mode**: `npm run auto-run:test` and platform variants -- **Production Mode**: `npm run auto-run:prod` and platform variants - -### Clean and Rebuild - -- Run relevant `clean:*` scripts and ensure re-build works - -## Emergency Procedures - -### Build System Broken - -1. **Immediate**: Revert to last known working commit -2. **Investigation**: Create issue with full error details -3. **Testing**: Verify all platforms work after revert -4. **Documentation**: Update `BUILDING.md` with failure notes -### Platform-Specific Failure - -1. **Isolate**: Identify which platform is affected -2. **Test Others**: Verify other platforms still work -3. **Rollback**: Revert platform-specific changes -4. **Investigation**: Debug in isolated environment - -## Integration Points - -### With Version Control - -- **Branch Protection**: Require reviews for build script changes -- **Commit Messages**: Must reference ADR for major changes -- **Testing**: All build changes must pass CI/CD pipeline - -### With Documentation - -- **BUILDING.md**: Must be updated for any script changes -- **README.md**: Must reflect new build requirements -- **CHANGELOG.md**: Must document breaking build changes - -### With Testing - -- **Pre-commit**: Run basic build validation -- **CI/CD**: Full platform build testing -- **Manual Testing**: Human verification of critical paths - -## Risk Matrix & Required Validation - -### Environment Handling - -- **Trigger**: Change to `.env.*` loading / variable names -- **Validation**: Prove `dev/test/prod` builds; show environment echo in logs - -### Script Flow - -- **Trigger**: Reorder steps (prebuild → build → package), new flags -- **Validation**: Dry-run + normal run, show exit codes & timing - -### Platform Packaging - -- **Trigger**: Electron NSIS/DMG/AppImage, Android/iOS bundle -- **Validation**: Produce installer/artifact and open it; verify single-instance, - icons, signing - -### Service Worker / WASM - -- **Trigger**: `sw_combine.js`, WASM copy path -- **Validation**: Verify combined SW exists and is injected; page loads offline; - WASM present - -### Docker - -- **Trigger**: New base image, build args -- **Validation**: Build image locally; run container; list produced `/dist` - -### Android Asset Management -- **Trigger**: Changes to `validate_android_assets()` function or resource paths -- **Validation**: Run `npm run build:android --assets` and verify all mipmap/drawable resources -- **Risk**: Missing splash screens or app icons causing build failures - -### Android API Routing -- **Trigger**: Changes to Android-specific API server IP logic -- **Validation**: Test both emulator (10.0.2.2) and custom IP modes -- **Risk**: API connectivity failures on different device types - -### Signing/Notarization - -- **Trigger**: Cert path/profiles -- **Validation**: Show signing logs + verify on target OS - -## PR Template (Paste into Description) - -- [ ] **Level**: L1 / L2 / L3 + justification -- [ ] **Files & platforms touched**: -- [ ] **Risk triggers & mitigations**: -- [ ] **Commands run (paste logs)**: -- [ ] **Artifacts (names + sha256)**: -- [ ] **Docs updated (sections/links)**: -- [ ] **Rollback steps verified**: -- [ ] **CI**: Jobs passing and artifacts uploaded - -## Rollback Playbook - -### Immediate Rollback - -1. `git revert` or `git reset --hard `; restore prior `scripts/` or config - files -2. Rebuild affected targets; verify old behavior returns -3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found - -### Rollback Verification - -- **Web**: `npm run build:web:dev` and `npm run build:web:prod` -- **Mobile**: `npm run build:android:test` and `npm run build:ios:test` -- **Desktop**: `npm run build:electron:dev` and packaging commands -- **Clean**: Run relevant `clean:*` scripts and verify re-build works - -### Android-Specific Rollback Verification -- **Asset Generation**: `npm run build:android --assets` - verify resources regenerate -- **API Routing**: Test both `--dev` and `--dev --api-ip ` modes -- **Resource Validation**: Check `android/app/src/main/res/` for all required assets -- **Build Modes**: Verify development, test, and production modes all work -- **Resource Fallback**: Confirm missing resources trigger automatic regeneration - -## ADR Trigger List - -Raise an ADR when you propose any of: - -- **New build stage** or reorder of canonical stages -- **Replacement of packager** / packaging format -- **New environment model** or secure secret handling scheme -- **New service worker assembly** strategy or cache policy -- **New Docker base** or multi-stage pipeline -- **Relocation of build outputs** or directory conventions -- **New Android build modes** or argument parsing logic -- **Changes to asset validation** or resource generation strategy -- **Modifications to platform-specific API routing** (Android emulator vs physical) -- **New Android deployment strategies** or device management - -**ADR must include**: motivation, alternatives, risks, validation plan, rollback, - doc diffs. - -## Competence Hooks - -### Why This Works - -- **Prevents Build Failures**: Catches issues before they reach production -- **Maintains Consistency**: Ensures all platforms build identically -- **Reduces Debugging Time**: Prevents build system regressions - -### Common Pitfalls - -- **Silent Failures**: Changes that work on one platform but break others -- **Dependency Conflicts**: Updates that create version incompatibilities -- **Documentation Drift**: Build scripts that don't match documentation - -### Next Skill Unlock - -- Learn to test build changes across all platforms simultaneously - -### Teach-back - -- "What three platforms must I test before committing a build script change?" - -## Collaboration Hooks - -### Team Review Requirements +- **Change** environment configurations -- **Platform Owners**: iOS, Android, Electron, Web specialists -- **DevOps**: CI/CD pipeline maintainers -- **QA**: Testing infrastructure owners +- **Modify** asset generation scripts -### Discussion Prompts +- **Alter** test infrastructure -- "Which platforms will be affected by this build change?" -- "How can we test this change without breaking existing builds?" -- "What's our rollback plan if this change fails?" +- **Update** platform SDK versions -## Self-Check (Before Allowing Changes) +--- -- [ ] **Authorization Level**: Is this change appropriate for the level? -- [ ] **Testing Plan**: Is there a comprehensive testing strategy? -- [ ] **Documentation**: Will BUILDING.md be updated? -- [ ] **Rollback**: Is there a safe rollback mechanism? -- [ ] **Team Review**: Have appropriate stakeholders been consulted? -- [ ] **CI/CD**: Will this pass the build pipeline? +**See also**: -## Continuous Improvement & Feedback +- `.cursor/rules/architecture/build_validation.mdc` for -### Feedback Collection + detailed validation procedures -The Build Architecture Guard system includes feedback mechanisms to continuously improve its effectiveness: +- `.cursor/rules/architecture/build_testing.mdc` for testing requirements -- **User Feedback**: Script includes feedback prompts for guard improvements -- **Pattern Analysis**: Monitor which file patterns trigger false positives/negatives -- **Documentation Gaps**: Track which changes lack proper documentation -- **Testing Effectiveness**: Measure how often guard catches actual issues +**Status**: Active build protection guidelines +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, DevOps team, Build team -### Feedback Integration Process +**Estimated Effort**: Ongoing vigilance +**Dependencies**: All build system components +**Stakeholders**: Development team, DevOps, Platform owners +**Next Review**: 2025-09-22 -1. **Collect Feedback**: Monitor guard execution logs and user reports -2. **Analyze Patterns**: Identify common false positives or missed patterns -3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback -4. **Enhance Script**: Update `build-arch-guard.sh` with new validations -5. **Test Changes**: Verify guard improvements don't introduce new issues -6. **Document Updates**: Update guard documentation with new patterns +## Model Implementation Checklist -### Feedback Categories +### Before Build Changes -- **False Positives**: Files flagged as sensitive that shouldn't be -- **False Negatives**: Sensitive files that weren't caught -- **Missing Patterns**: New file types that should be protected -- **Overly Strict**: Patterns that are too restrictive -- **Documentation Gaps**: Missing guidance for specific change types -- **Testing Improvements**: Better validation procedures +- [ ] **Change Level**: Determine if change is L1, L2, or L3 +- [ ] **Impact Assessment**: Assess impact on build system architecture +- [ ] **ADR Requirement**: Check if ADR is required for major changes +- [ ] **Testing Planning**: Plan appropriate testing for change level -### Feedback Reporting +### During Build Changes -When reporting guard issues, include: -- **File patterns** that triggered false positives/negatives -- **Build system changes** that weren't properly caught -- **Documentation gaps** in current guard rules -- **Testing procedures** that could be improved -- **User experience** issues with guard enforcement +- [ ] **Guard Compliance**: Ensure changes comply with build architecture guard +- [ ] **Documentation**: Document changes according to level requirements +- [ ] **Testing**: Execute appropriate testing for change level +- [ ] **Review Process**: Follow required review process for change level ---- +### After Build Changes -**Status**: Active build system protection -**Priority**: Critical -**Estimated Effort**: Ongoing vigilance -**Dependencies**: All build system components -**Stakeholders**: Development team, DevOps, Platform owners -**Next Review**: 2025-09-22 +- [ ] **Validation**: Verify build system still functions correctly +- [ ] **Documentation Update**: Update relevant documentation +- [ ] **Team Communication**: Communicate changes to affected teams +- [ ] **Monitoring**: Monitor for any build system issues diff --git a/.cursor/rules/architecture/build_testing.mdc b/.cursor/rules/architecture/build_testing.mdc new file mode 100644 index 00000000..4d0301dc --- /dev/null +++ b/.cursor/rules/architecture/build_testing.mdc @@ -0,0 +1,248 @@ +# Build Testing — Requirements and Emergency Procedures + +> **Agent role**: Reference this file for testing requirements and + emergency procedures when working with build architecture changes. + +## Emergency Procedures + +### Build System Broken + +1. **Immediate**: Revert to last known working commit + +2. **Investigation**: Create issue with full error details + +3. **Testing**: Verify all platforms work after revert + +4. **Documentation**: Update `BUILDING.md` with failure notes + +### Platform-Specific Failure + +1. **Isolate**: Identify which platform is affected + +2. **Test Others**: Verify other platforms still work + +3. **Rollback**: Revert platform-specific changes + +4. **Investigation**: Debug in isolated environment + +## Rollback Playbook + +### Immediate Rollback + +1. `git revert` or `git reset --hard `; restore prior `scripts/` or config + + files + +2. Rebuild affected targets; verify old behavior returns + +3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found + +### Rollback Verification + +- **Web**: `npm run build:web:dev` and `npm run build:web:prod` + +- **Mobile**: `npm run build:android:test` and `npm run build:ios:test` + +- **Desktop**: `npm run build:electron:dev` and packaging commands + +- **Clean**: Run relevant `clean:*` scripts and verify re-build works + +### Android-Specific Rollback Verification + +- **Asset Generation**: `npm run build:android --assets` - + + verify resources regenerate + +- **API Routing**: Test both `--dev` and `--dev --api-ip ` modes + +- **Resource Validation**: + + Check `android/app/src/main/res/` for all required assets + +- **Build Modes**: Verify development, test, and production modes all work + +- **Resource Fallback**: + + Confirm missing resources trigger automatic regeneration + +## Integration Points + +### With Version Control + +- **Branch Protection**: Require reviews for build script changes + +- **Commit Messages**: Must reference ADR for major changes + +- **Testing**: All build changes must pass CI/CD pipeline + +### With Documentation + +- **BUILDING.md**: Must be updated for any script changes + +- **README.md**: Must reflect new build requirements + +- **CHANGELOG.md**: Must document breaking build changes + +### With Testing + +- **Pre-commit**: Run basic build validation + +- **CI/CD**: Full platform build testing + +- **Manual Testing**: Human verification of critical paths + +## Competence Hooks + +### Why This Works + +- **Prevents Build Failures**: Catches issues before they reach production + +- **Maintains Consistency**: Ensures all platforms build identically + +- **Reduces Debugging Time**: Prevents build system regressions + +### Common Pitfalls + +- **Silent Failures**: Changes that work on one platform but break others + +- **Dependency Conflicts**: Updates that create version incompatibilities + +- **Documentation Drift**: Build scripts that don't match documentation + +### Next Skill Unlock + +- Learn to test build changes across all platforms simultaneously + +### Teach-back + +- "What three platforms must I test before committing a build script change?" + +## Collaboration Hooks + +### Team Review Requirements + +- **Platform Owners**: iOS, Android, Electron, Web specialists + +- **DevOps**: CI/CD pipeline maintainers + +- **QA**: Testing infrastructure owners + +### Discussion Prompts + +- "Which platforms will be affected by this build change?" + +- "How can we test this change without breaking existing builds?" + +- "What's our rollback plan if this change fails?" + +## Self-Check (Before Allowing Changes) + +- [ ] **Authorization Level**: Is this change appropriate for the level? + +- [ ] **Testing Plan**: Is there a comprehensive testing strategy? + +- [ ] **Documentation**: Will BUILDING.md be updated? + +- [ ] **Rollback**: Is there a safe rollback mechanism? + +- [ ] **Team Review**: Have appropriate stakeholders been consulted? + +- [ ] **CI/CD**: Will this pass the build pipeline? + +## Continuous Improvement & Feedback + +### Feedback Collection + +The Build Architecture Guard system includes feedback mechanisms to continuously + improve its effectiveness: + +- **User Feedback**: Script includes feedback prompts for guard improvements + +- **Pattern Analysis**: + + Monitor which file patterns trigger false positives/negatives + +- **Documentation Gaps**: Track which changes lack proper documentation + +- **Testing Effectiveness**: Measure how often guard catches actual issues + +### Feedback Integration Process + +1. **Collect Feedback**: Monitor guard execution logs and user reports + +2. **Analyze Patterns**: Identify common false positives or missed patterns + +3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback + +4. **Enhance Script**: Update `build-arch-guard.sh` with new validations + +5. **Test Changes**: Verify guard improvements don't introduce new issues + +6. **Document Updates**: Update guard documentation with new patterns + +### Feedback Categories + +- **False Positives**: Files flagged as sensitive that shouldn't be + +- **False Negatives**: Sensitive files that weren't caught + +- **Missing Patterns**: New file types that should be protected + +- **Overly Strict**: Patterns that are too restrictive + +- **Documentation Gaps**: Missing guidance for specific change types + +- **Testing Improvements**: Better validation procedures + +### Feedback Reporting + +When reporting guard issues, include: + +- **File patterns** that triggered false positives/negatives + +- **Build system changes** that weren't properly caught + +- **Documentation gaps** in current guard rules + +- **Testing procedures** that could be improved + +- **User experience** issues with guard enforcement + +--- + +**See also**: + +- `.cursor/rules/architecture/build_architecture_guard.mdc` for + + core protection guidelines + +- `.cursor/rules/architecture/build_validation.mdc` for validation procedures + +**Status**: Active testing requirements +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: build_architecture_guard.mdc, build_validation.mdc +**Stakeholders**: Development team, DevOps team, Build team + +## Model Implementation Checklist + +### Before Build Testing + +- [ ] **Test Planning**: Plan comprehensive testing strategy for build changes +- [ ] **Platform Coverage**: Identify all platforms that need testing +- [ ] **Risk Assessment**: Assess testing risks and mitigation strategies +- [ ] **Resource Planning**: Plan testing resources and time requirements + +### During Build Testing + +- [ ] **Test Execution**: Execute planned tests across all platforms +- [ ] **Issue Tracking**: Track and document any issues found +- [ ] **Feedback Collection**: Collect feedback on testing effectiveness +- [ ] **Documentation**: Document testing procedures and results + +### After Build Testing + +- [ ] **Result Analysis**: Analyze testing results and identify patterns +- [ ] **Feedback Integration**: Integrate feedback into testing procedures +- [ ] **Process Improvement**: Update testing procedures based on feedback +- [ ] **Team Communication**: Share testing results and improvements with team diff --git a/.cursor/rules/architecture/build_validation.mdc b/.cursor/rules/architecture/build_validation.mdc new file mode 100644 index 00000000..da78c63f --- /dev/null +++ b/.cursor/rules/architecture/build_validation.mdc @@ -0,0 +1,224 @@ +# Build Validation — Procedures and Requirements + +> **Agent role**: Reference this file for + detailed validation procedures when working with build architecture changes. + +## Required Validation Checklist + +### Before Any Build System Change + +- [ ] **Impact Assessment**: Which platforms are affected? + +- [ ] **Testing Plan**: How will this be tested across platforms? + +- [ ] **Rollback Plan**: How can this be reverted if it breaks? + +- [ ] **Documentation**: Will `BUILDING.md` need updates? + +- [ ] **Dependencies**: Are all required tools available? + +### After Build System Change + +- [ ] **Web Platform**: Does `npm run build:web:dev` work? + +- [ ] **Mobile Platforms**: Do iOS/Android builds succeed? + +- [ ] **Desktop Platform**: Does Electron build and run? + +- [ ] **Tests Pass**: Do all build-related tests pass? + +- [ ] **Documentation Updated**: Is `BUILDING.md` current? + +## Specific Test Commands (Minimum Required) + +### Web Platform + +- **Development**: `npm run build:web:dev` - serve and load app + +- **Production**: `npm run build:web:prod` - verify SW and WASM present + +### Mobile Platforms + +- **Android**: `npm run build:android:test` or `:prod` - confirm assets copied + +- **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds + +### Android Platform (Enhanced) + +- **Development Mode**: `npm run build:android --dev` - + + verify 10.0.2.2 API routing + +- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` - + + verify custom IP + +- **Asset Validation**: `npm run build:android --assets` - + + verify resource generation + +- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment + +### Desktop Platform + +- **Electron**: `npm run build:electron:dev` and packaging for target OS + +- **Verify**: Single-instance behavior and app boot + +### Auto-run (if affected) + +- **Test Mode**: `npm run auto-run:test` and platform variants + +- **Production Mode**: `npm run auto-run:prod` and platform variants + +### Clean and Rebuild + +- Run relevant `clean:*` scripts and ensure re-build works + +## Risk Matrix & Required Validation + +### Environment Handling + +- **Trigger**: Change to `.env.*` loading / variable names + +- **Validation**: Prove `dev/test/prod` builds; show environment echo in logs + +### Script Flow + +- **Trigger**: Reorder steps (prebuild → build → package), new flags + +- **Validation**: Dry-run + normal run, show exit codes & timing + +### Platform Packaging + +- **Trigger**: Electron NSIS/DMG/AppImage, Android/iOS bundle + +- **Validation**: Produce installer/artifact and open it; + + verify single-instance, + icons, signing + +### Service Worker / WASM + +- **Trigger**: `sw_combine.js`, WASM copy path + +- **Validation**: Verify combined SW exists and is injected; page loads offline; + + WASM present + +### Docker + +- **Trigger**: New base image, build args + +- **Validation**: Build image locally; run container; list produced `/dist` + +### Android Asset Management + +- **Trigger**: Changes to `validate_android_assets()` function or resource paths + +- **Validation**: + + Run `npm run build:android --assets` and verify all mipmap/drawable resources + +- **Risk**: Missing splash screens or app icons causing build failures + +### Android API Routing + +- **Trigger**: Changes to Android-specific API server IP logic + +- **Validation**: Test both emulator (10.0.2.2) and custom IP modes + +- **Risk**: API connectivity failures on different device types + +### Signing/Notarization + +- **Trigger**: Cert path/profiles + +- **Validation**: Show signing logs + verify on target OS + +## PR Template (Paste into Description) + +- [ ] **Level**: L1 / L2 / L3 + justification + +- [ ] **Files & platforms touched**: + +- [ ] **Risk triggers & mitigations**: + +- [ ] **Commands run (paste logs)**: + +- [ ] **Artifacts (names + sha256)**: + +- [ ] **Docs updated (sections/links)**: + +- [ ] **Rollback steps verified**: + +- [ ] **CI**: Jobs passing and artifacts uploaded + +## ADR Trigger List + +Raise an ADR when you propose any of: + +- **New build stage** or reorder of canonical stages + +- **Replacement of packager** / packaging format + +- **New environment model** or secure secret handling scheme + +- **New service worker assembly** strategy or cache policy + +- **New Docker base** or multi-stage pipeline + +- **Relocation of build outputs** or directory conventions + +- **New Android build modes** or argument parsing logic + +- **Changes to asset validation** or resource generation strategy + +- **Modifications to platform-specific API routing** ( + + Android emulator vs physical) + +- **New Android deployment strategies** or device management + +**ADR must include**: + motivation, alternatives, risks, validation plan, rollback, + doc diffs. + +--- + +**See also**: + +- `.cursor/rules/architecture/build_architecture_guard.mdc` for + + core protection guidelines + +- `.cursor/rules/architecture/build_testing.mdc` for testing requirements + +**Status**: Active validation procedures +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: build_architecture_guard.mdc +**Stakeholders**: Development team, DevOps team, Build team + +## Model Implementation Checklist + +### Before Build Changes + +- [ ] **Level Assessment**: Determine build validation level (L1/L2/L3) +- [ ] **Platform Analysis**: Identify all platforms affected by changes +- [ ] **Risk Assessment**: Identify risk triggers and mitigation strategies +- [ ] **Rollback Planning**: Plan rollback steps for build failures + +### During Build Implementation + +- [ ] **Validation Commands**: Run appropriate validation commands for level +- [ ] **Platform Testing**: Test changes across all affected platforms +- [ ] **Risk Mitigation**: Implement identified risk mitigation strategies +- [ ] **Documentation**: Document all commands run and their outputs + +### After Build Implementation + +- [ ] **Artifact Validation**: Verify build artifacts are correct and accessible +- [ ] **CI Verification**: Ensure CI jobs pass and artifacts are uploaded +- [ ] **Documentation Update**: Update relevant documentation sections +- [ ] **Team Communication**: Share build validation results with team diff --git a/.cursor/rules/base_context.mdc b/.cursor/rules/core/base_context.mdc similarity index 78% rename from .cursor/rules/base_context.mdc rename to .cursor/rules/core/base_context.mdc index 4585c232..a1ad4bce 100644 --- a/.cursor/rules/base_context.mdc +++ b/.cursor/rules/core/base_context.mdc @@ -1,7 +1,8 @@ --- -alwaysApply: true +alwaysApply: false --- ```json + { "coaching_level": "standard", "socratic_max_questions": 7, @@ -9,6 +10,7 @@ alwaysApply: true "timebox_minutes": null, "format_enforcement": "strict" } + ``` # Base Context — Human Competence First @@ -30,13 +32,21 @@ 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 @@ -72,12 +82,19 @@ 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 @@ -91,11 +108,17 @@ 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. @@ -103,42 +126,85 @@ 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. ## Related Rulesets - **software_development.mdc**: For software-specific development practices + - **research_diagnostic.mdc**: For investigation and research workflows +## Model Implementation Checklist + +### Before Responding + +- [ ] **Toggle Review**: Check coaching_level, socratic_max_questions, verbosity, + timebox_minutes +- [ ] **Mode Selection**: Choose appropriate mode(s) for the task +- [ ] **Scope Understanding**: Clarify requirements and constraints +- [ ] **Context Analysis**: Review relevant rulesets and dependencies + +### During Response Creation + +- [ ] **Output Contract**: Include all required sections (Objective, Result, + Use/Run, etc.) +- [ ] **Competence Hooks**: Add at least one learning lever (≤120 words total) +- [ ] **Collaboration Hooks**: Include discussion prompts or review steps +- [ ] **Toggle Compliance**: Respect verbosity, timebox, and format settings + +### After Response Creation + +- [ ] **Self-Check**: Verify all checklist items are completed +- [ ] **Format Validation**: Ensure output follows required structure +- [ ] **Content Review**: Confirm no disallowed content included +- [ ] **Quality Assessment**: Verify response meets human competence goals + ## 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. + 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 - [ ] Uncertainties/assumptions surfaced. - [ ] No disallowed content. @@ -149,6 +215,3 @@ Default: Doer + short Mentor notes. **Estimated Effort**: Ongoing reference **Dependencies**: None (base ruleset) **Stakeholders**: All AI interactions - -- [ ] Uncertainties/assumptions surfaced. -- [ ] No disallowed content. diff --git a/.cursor/rules/core/harbor_pilot_universal.mdc b/.cursor/rules/core/harbor_pilot_universal.mdc new file mode 100644 index 00000000..3226e93e --- /dev/null +++ b/.cursor/rules/core/harbor_pilot_universal.mdc @@ -0,0 +1,224 @@ +```json + +{ + "coaching_level": "standard", + "socratic_max_questions": 2, + "verbosity": "concise", + "timebox_minutes": 10, + "format_enforcement": "strict" +} + +``` + +# Harbor Pilot Universal — Technical Guide Standards + +> **Agent role**: When creating technical guides, reference documents, or +> implementation plans, apply these universal directives to ensure consistent +> quality and structure. + +## Purpose + +- **Purpose fit**: Prioritizes human competence and collaboration while + + delivering reproducible artifacts. + +- **Output Contract**: This directive **adds universal constraints** for any + + technical topic while **inheriting** the Base Context contract sections. + +- **Toggles honored**: Uses the same toggle semantics; defaults above can be + + overridden by the caller. + +## Core Directive + +Produce a **developer-grade, reproducible guide** for any technical topic +that onboards a competent practitioner **without meta narration** and **with +evidence-backed steps**. + +## Required Elements + +### 1. Time & Date Standards + +- Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid + + "today/yesterday". + +- Include at least **one diagram** (Mermaid preferred). Choose the most + + fitting type: + + - `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`, + + `gantt` (timelines), or `classDiagram` (schemas). + +### 2. Evidence Requirements + +- **Reproducible Steps**: Every claim must have copy-paste commands + +- **Verifiable Outputs**: Include expected results, status codes, or + + error messages + +- **Cite evidence** for *Works/Doesn't* items (timestamps, filenames, + + line numbers, IDs/status codes, or logs). + +## Required Sections + +Follow this exact order **after** the Base Contract's **Objective → Result +→ Use/Run** headers: + +1. **Artifacts & Links** - Repos/PRs, design docs, datasets/HARs/pcaps, + + scripts/tools, dashboards. + +2. **Environment & Preconditions** - OS/runtime, versions/build IDs, + + services/endpoints/URLs, credentials/auth mode. + +3. **Architecture / Process Overview** - Short prose + **one diagram** + + selected from the list above. + +4. **Interfaces & Contracts** - Choose one: API-based (endpoint table), + + Data/Files (I/O contract), or Systems/Hardware (interfaces). + +5. **Repro: End-to-End Procedure** - Minimal copy-paste steps with + + code/commands and **expected outputs**. +6. **What Works (with Evidence)** - Each item: **Time (UTC)** • + **Artifact/Req IDs** • **Status/Result** • **Where to verify**. +7. **What Doesn't (Evidence & Hypotheses)** - Each failure: locus, + evidence snippet; short hypothesis and **next probe**. +8. **Risks, Limits, Assumptions** - SLOs/limits, rate/size caps, + security boundaries, retries/backoff/idempotency patterns. +9. **Next Steps (Owner • Exit Criteria • Target Date)** - Actionable, + assigned, and time-bound. + +## Quality Standards + +### Do + +- **Do** quantify progress only against a defined scope with acceptance + + criteria. + +- **Do** include minimal sample payloads/headers or I/O schemas; redact + + sensitive values. + +- **Do** keep commentary lean; if timeboxed, move depth to **Deferred + + for depth**. + +- **Do** use specific, actionable language that guides implementation. + +### Don't + +- **Don't** use marketing language or meta narration ("Perfect!", + + "tool called", "new chat"). + +- **Don't** include IDE-specific chatter or internal rules unrelated to + + the task. + +- **Don't** assume reader knowledge; provide context for all technical + + decisions. + +## Model Implementation Checklist + +### Before Creating Technical Guides + +- [ ] **Scope Definition**: Clearly define problem, audience, and scope +- [ ] **Evidence Collection**: Gather specific timestamps, file references, and logs +- [ ] **Diagram Planning**: Plan appropriate diagram type for the technical process +- [ ] **Template Selection**: Choose relevant sections from required sections list + +### During Guide Creation + +- [ ] **Evidence Integration**: Include UTC timestamps and verifiable evidence +- [ ] **Diagram Creation**: Create Mermaid diagram that illustrates the process +- [ ] **Repro Steps**: Write copy-paste ready commands with expected outputs +- [ ] **Section Completion**: Fill in all required sections completely + +### After Guide Creation + +- [ ] **Validation**: Run through the validation checklist below +- [ ] **Evidence Review**: Verify all claims have supporting evidence +- [ ] **Repro Testing**: Test reproduction steps to ensure they work +- [ ] **Peer Review**: Share with technical leads for feedback + +## Validation Checklist + +Before publishing, verify: + +- [ ] **Diagram included** and properly formatted (Mermaid syntax valid) +- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for + each endpoint +- [ ] **Environment section** includes all required dependencies and + versions +- [ ] Every Works/Doesn't item has **UTC timestamp**, **status/result**, + and **verifiable evidence** +- [ ] **Repro steps** are copy-paste ready with expected outputs +- [ ] Base **Output Contract** sections satisfied + (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References) + +## Integration Points + +### Base Context Integration + +- Apply historical comment management rules (see + + `.cursor/rules/development/historical_comment_management.mdc`) + +- Apply realistic time estimation rules (see + + `.cursor/rules/development/realistic_time_estimation.mdc`) + +### Competence Hooks + +- **Why this works**: Structured approach ensures completeness and + + reproducibility + +- **Common pitfalls**: Skipping evidence requirements, vague language + +- **Next skill unlock**: Practice creating Mermaid diagrams for different + + use cases + +- **Teach-back**: Explain how you would validate this guide's + + reproducibility + +### Collaboration Hooks + +- **Reviewers**: Technical leads, subject matter experts + +- **Stakeholders**: Development teams, DevOps, QA teams + +--- + +**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human +Competence First* + +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: base_context.mdc +**Stakeholders**: All AI interactions, Development teams + +## Example Diagram Template + +```mermaid + + + +``` + +**Note**: Replace the placeholder with an actual diagram that illustrates +the technical process, architecture, or workflow being documented. diff --git a/.cursor/rules/core/less_complex.mdc b/.cursor/rules/core/less_complex.mdc new file mode 100644 index 00000000..6c5ca71d --- /dev/null +++ b/.cursor/rules/core/less_complex.mdc @@ -0,0 +1,99 @@ + +alwaysApply: false + +--- + +# Minimalist Solution Principle (Cursor MDC) + +role: Engineering assistant optimizing for least-complex changes +focus: Deliver the smallest viable diff that fully resolves the current +bug/feature. Defer generalization unless justified with evidence. +language: Match repository languages and conventions + +## Rules + +1. **Default to the least complex solution.** Fix the problem directly + where it occurs; avoid new layers, indirection, or patterns unless + strictly necessary. +2. **Keep scope tight.** Implement only what is needed to satisfy the + acceptance criteria and tests for *this* issue. +3. **Avoid speculative abstractions.** Use the **Rule of Three**: + don't extract helpers/patterns until the third concrete usage proves + the shape. +4. **No drive-by refactors.** Do not rename, reorder, or reformat + unrelated code in the same change set. +5. **Minimize surface area.** Prefer local changes over cross-cutting + rewires; avoid new public APIs unless essential. +6. **Be dependency-frugal.** Do not add packages or services for + single, simple needs unless there's a compelling, documented reason. +7. **Targeted tests only.** Add the smallest set of tests that prove + the fix and guard against regression; don't rewrite suites. +8. **Document the "why enough."** Include a one-paragraph note + explaining why this minimal solution is sufficient *now*. + +## Future-Proofing Requires Evidence + Discussion + +Any added complexity "for the future" **must** include: + +- A referenced discussion/ADR (or issue link) summarizing the decision. +- **Substantial evidence**, e.g.: + - Recurring incidents or tickets that this prevents (list IDs). + - Benchmarks or profiling showing a real bottleneck. + - Concrete upcoming requirements with dates/owners, not hypotheticals. + - Risk assessment comparing maintenance cost vs. expected benefit. +- A clear trade-off table showing why minimal won't suffice. + +If this evidence is not available, **ship the minimal fix** and open a +follow-up discussion item. + +## PR / Change Checklist (enforced by reviewer + model) + +- [ ] Smallest diff that fully fixes the issue (attach `git diff --stat` + if useful). +- [ ] No unrelated refactors or formatting. +- [ ] No new dependencies, or justification + ADR link provided. +- [ ] Abstractions only if ≥3 call sites or strong evidence says + otherwise (cite). +- [ ] Targeted tests proving the fix/regression guard. +- [ ] Short "Why this is enough now" note in the PR description. +- [ ] Optional: "Future Work (non-blocking)" section listing deferred + ideas. + +## Assistant Output Contract + +When proposing a change, provide: + +1. **Minimal Plan**: 3–6 bullet steps scoped to the immediate fix. +2. **Patch Sketch**: Focused diffs/snippets touching only necessary + files. +3. **Risk & Rollback**: One paragraph each on risk, quick rollback, + and test points. +4. **(If proposing complexity)**: Link/inline ADR summary + evidence + + trade-offs; otherwise default to minimal. + + One paragraph each on risk, quick rollback, and test points. +5. **(If proposing complexity)**: Link/inline ADR summary + evidence + + trade-offs; otherwise default to minimal. + +## Model Implementation Checklist + +### Before Proposing Changes + +- [ ] **Problem Analysis**: Clearly understand the specific issue scope +- [ ] **Evidence Review**: Gather evidence that justifies the change +- [ ] **Complexity Assessment**: Evaluate if change requires added complexity +- [ ] **Alternative Research**: Consider simpler solutions first + +### During Change Design + +- [ ] **Minimal Scope**: Design solution that addresses only the current issue +- [ ] **Evidence Integration**: Include specific evidence for any complexity +- [ ] **Dependency Review**: Minimize new dependencies and packages +- [ ] **Testing Strategy**: Plan minimal tests that prove the fix + +### After Change Design + +- [ ] **Self-Review**: Verify solution follows minimalist principles +- [ ] **Evidence Validation**: Confirm all claims have supporting evidence +- [ ] **Complexity Justification**: Document why minimal approach suffices +- [ ] **Future Work Planning**: Identify deferred improvements for later diff --git a/.cursor/rules/database/absurd-sql.mdc b/.cursor/rules/database/absurd-sql.mdc index 954fd8f7..9f959dfc 100644 --- a/.cursor/rules/database/absurd-sql.mdc +++ b/.cursor/rules/database/absurd-sql.mdc @@ -1,8 +1,10 @@ --- -globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, **/src/registerSQLWorker.js, **/ +globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, + **/src/registerSQLWorker.js, **/ services/AbsurdSqlDatabaseService.ts alwaysApply: false --- + # Absurd SQL - Cursor Development Guide **Author**: Matthew Raymer @@ -19,12 +21,14 @@ in Cursor. ## Project Structure ``` + absurd-sql/ ├── src/ # Source code ├── dist/ # Built files ├── package.json # Dependencies and scripts ├── rollup.config.js # Build configuration └── jest.config.js # Test configuration + ``` ## Development Rules @@ -32,13 +36,17 @@ absurd-sql/ ### 1. Worker Thread Requirements - All SQL operations MUST be performed in a worker thread + - Main thread should only handle worker initialization and communication + - Never block the main thread with database operations ### 2. Code Organization - Keep worker code in separate files (e.g., `*.worker.js`) + - Use ES modules for imports/exports + - Follow the project's existing module structure ### 3. Required Headers @@ -46,14 +54,18 @@ absurd-sql/ When developing locally or deploying, ensure these headers are set: ``` + Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp + ``` ### 4. Browser Compatibility - Primary target: Modern browsers with SharedArrayBuffer support + - Fallback mode: Safari (with limitations) + - Always test in both modes ### 5. Database Configuration @@ -61,8 +73,10 @@ Cross-Origin-Embedder-Policy: require-corp Recommended database settings: ```sql + PRAGMA journal_mode=MEMORY; PRAGMA page_size=8192; -- Optional, but recommended + ``` ### 6. Development Workflow @@ -70,54 +84,77 @@ PRAGMA page_size=8192; -- Optional, but recommended 1. Install dependencies: ```bash + yarn add @jlongster/sql.js absurd-sql + ``` 2. Development commands: + - `yarn build` - Build the project + - `yarn jest` - Run tests + - `yarn serve` - Start development server ### 7. Testing Guidelines - Write tests for both SharedArrayBuffer and fallback modes + - Use Jest for testing + - Include performance benchmarks for critical operations ### 8. Performance Considerations - Use bulk operations when possible + - Monitor read/write performance + - Consider using transactions for multiple operations + - Avoid unnecessary database connections ### 9. Error Handling - Implement proper error handling for: + - Worker initialization failures + - Database connection issues + - Concurrent access conflicts (in fallback mode) + - Storage quota exceeded scenarios ### 10. Security Best Practices - Never expose database operations directly to the client + - Validate all SQL queries + - Implement proper access controls + - Handle sensitive data appropriately ### 11. Code Style - Follow ESLint configuration + - Use async/await for asynchronous operations + - Document complex database operations + - Include comments for non-obvious optimizations ### 12. Debugging - Use `jest-debug` for debugging tests + - Monitor IndexedDB usage in browser dev tools + - Check worker communication in console + - Use performance monitoring tools ## Common Patterns @@ -125,6 +162,7 @@ PRAGMA page_size=8192; -- Optional, but recommended ### Worker Initialization ```javascript + // Main thread import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread'; @@ -132,11 +170,13 @@ function init() { let worker = new Worker(new URL('./index.worker.js', import.meta.url)); initBackend(worker); } + ``` ### Database Setup ```javascript + // Worker thread import initSqlJs from '@jlongster/sql.js'; import { SQLiteFS } from 'absurd-sql'; @@ -146,12 +186,13 @@ async function setupDatabase() { let SQL = await initSqlJs({ locateFile: file => file }); let sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend()); SQL.register_for_idb(sqlFS); - + SQL.FS.mkdir('/sql'); SQL.FS.mount(sqlFS, {}, '/sql'); - + return new SQL.Database('/sql/db.sqlite', { filename: true }); } + ``` ## Troubleshooting @@ -159,25 +200,37 @@ async function setupDatabase() { ### Common Issues 1. SharedArrayBuffer not available + - Check COOP/COEP headers + - Verify browser support + - Test fallback mode 2. Worker initialization failures + - Check file paths + - Verify module imports + - Check browser console for errors 3. Performance issues + - Monitor IndexedDB usage + - Check for unnecessary operations + - Verify transaction usage ## Resources - [Project Demo](https://priceless-keller-d097e5.netlify.app/) + - [Example Project](https://github.com/jlongster/absurd-example-project) + - [Blog Post](https://jlongster.com/future-sql-web) + - [SQL.js Documentation](https://github.com/sql-js/sql.js/) --- @@ -186,8 +239,35 @@ async function setupDatabase() { **Priority**: High **Estimated Effort**: Ongoing reference **Dependencies**: Absurd SQL, SQL.js, IndexedDB -**Stakeholders**: Development team, Database team +**Stakeholders**: Development team, Database team + - [Project Demo](https://priceless-keller-d097e5.netlify.app/) + - [Example Project](https://github.com/jlongster/absurd-example-project) + - [Blog Post](https://jlongster.com/future-sql-web) + - [SQL.js Documentation](https://github.com/sql-js/sql.js/) + +## Model Implementation Checklist + +### Before Absurd SQL Implementation + +- [ ] **Browser Support**: Verify SharedArrayBuffer and COOP/COEP support +- [ ] **Worker Setup**: Plan worker thread initialization and communication +- [ ] **Database Planning**: Plan database schema and initialization +- [ ] **Performance Planning**: Plan performance monitoring and optimization + +### During Absurd SQL Implementation + +- [ ] **Worker Initialization**: Set up worker threads with proper communication +- [ ] **Database Setup**: Initialize SQLite database with IndexedDB backend +- [ ] **File System**: Configure SQLiteFS with proper mounting +- [ ] **Error Handling**: Implement proper error handling for worker failures + +### After Absurd SQL Implementation + +- [ ] **Cross-Browser Testing**: Test across different browsers and devices +- [ ] **Performance Validation**: Monitor IndexedDB usage and performance +- [ ] **Worker Validation**: Verify worker communication and database operations +- [ ] **Documentation**: Update Absurd SQL implementation documentation diff --git a/.cursor/rules/database/legacy_dexie.mdc b/.cursor/rules/database/legacy_dexie.mdc index ac02aaba..ffb9e8f3 100644 --- a/.cursor/rules/database/legacy_dexie.mdc +++ b/.cursor/rules/database/legacy_dexie.mdc @@ -1,8 +1,62 @@ +# Legacy Dexie Database — Migration Guidelines + +> **Agent role**: Reference this file when working with legacy Dexie +> database code or migration patterns. + +## Overview + +All references in the codebase to Dexie apply only to migration from +IndexedDb to Absurd SQL. Dexie is no longer used for new development. + +## Migration Status + +- **Legacy Code**: Existing Dexie implementations being migrated +- **Target**: Absurd SQL with IndexedDB backend +- **Timeline**: Gradual migration as features are updated + +## Key Principles + +- **No New Dexie**: All new database operations use Absurd SQL +- **Migration Path**: Legacy code should be migrated when updated +- **Backward Compatibility**: Maintain existing functionality during + migration + +## Integration Points + +- Apply these rules when updating database-related code +- Use during feature development and refactoring +- Include in database architecture decisions + --- -globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue -alwaysApply: false ---- -# What to do with Dexie -All references in the codebase to Dexie apply only to migration from IndexedDb to -Sqlite and will be deprecated in future versions. +**Status**: Legacy migration guidelines +**Priority**: Low +**Estimated Effort**: Ongoing reference +**Dependencies**: absurd-sql.mdc +**Stakeholders**: Database team, Development team + +All references in the codebase to Dexie apply only to migration from IndexedDb +to Sqlite and will be deprecated in future versions. + +## Model Implementation Checklist + +### Before Legacy Dexie Work + +- [ ] **Migration Analysis**: Identify legacy Dexie code that needs migration +- [ ] **Target Planning**: Plan migration to Absurd SQL with IndexedDB backend +- [ ] **Backward Compatibility**: Plan to maintain existing functionality +- [ ] **Testing Strategy**: Plan testing approach for migration + +### During Legacy Dexie Migration + +- [ ] **No New Dexie**: Ensure no new Dexie code is introduced +- [ ] **Migration Implementation**: Implement migration to Absurd SQL +- [ ] **Functionality Preservation**: Maintain existing functionality during migration +- [ ] **Error Handling**: Implement proper error handling for migration + +### After Legacy Dexie Migration + +- [ ] **Functionality Testing**: Verify all functionality still works correctly +- [ ] **Performance Validation**: Ensure performance meets or exceeds legacy +- [ ] **Documentation Update**: Update database documentation +- [ ] **Legacy Cleanup**: Remove deprecated Dexie code diff --git a/.cursor/rules/asset_configuration.mdc b/.cursor/rules/development/asset_configuration.mdc similarity index 62% rename from .cursor/rules/asset_configuration.mdc rename to .cursor/rules/development/asset_configuration.mdc index aa493fe9..a53e9ffb 100644 --- a/.cursor/rules/asset_configuration.mdc +++ b/.cursor/rules/development/asset_configuration.mdc @@ -2,6 +2,7 @@ description: when doing anything with capacitor assets alwaysApply: false --- + # Asset Configuration Directive **Author**: Matthew Raymer @@ -14,28 +15,43 @@ orchestration* ## Intent - Version **asset configuration files** (optionally dev-time generated). + - **Do not** version platform asset outputs (Android/iOS/Electron); generate + them **at build-time** with standard tools. + - Keep existing per-platform build scripts unchanged. ## Source of Truth - **Preferred (Capacitor default):** `resources/` as the single master source. + - **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is + explicitly configured to read from it. + - **Never** maintain both `resources/` and `assets/` as parallel sources. + Migrate and delete the redundant folder. ## Config Files - Live under: `config/assets/` (committed). + - Examples: + - `config/assets/capacitor-assets.config.json` (or the path the tool + expects) + - `config/assets/android.assets.json` + - `config/assets/ios.assets.json` + - `config/assets/common.assets.yaml` (optional shared layer) + - **Dev-time generation allowed** for these configs; **build-time + generation is forbidden**. ## Build-Time Behavior @@ -43,10 +59,13 @@ orchestration* - Build generates platform assets (not configs) using the standard chain: ```bash + npm run build:capacitor # web build via Vite (.mts) npx cap sync npx capacitor-assets generate # produces platform assets; not committed + # then platform-specific build steps + ``` --- @@ -58,4 +77,29 @@ npx capacitor-assets generate # produces platform assets; not committed **Stakeholders**: Development team, Build team npx capacitor-assets generate # produces platform assets; not committed - # then platform-specific build steps + +# then platform-specific build steps + +## Model Implementation Checklist + +### Before Asset Configuration + +- [ ] **Source Review**: Identify current asset source location (`resources/` or + `assets/`) +- [ ] **Tool Assessment**: Verify capacitor-assets toolchain is available +- [ ] **Config Planning**: Plan configuration file structure and location +- [ ] **Platform Analysis**: Understand asset requirements for all target platforms + +### During Asset Configuration + +- [ ] **Source Consolidation**: Ensure single source of truth (prefer `resources/`) +- [ ] **Config Creation**: Create platform-specific asset configuration files +- [ ] **Tool Integration**: Configure capacitor-assets to read from correct source +- [ ] **Build Integration**: Integrate asset generation into build pipeline + +### After Asset Configuration + +- [ ] **Build Testing**: Verify assets generate correctly at build time +- [ ] **Platform Validation**: Test asset generation across all platforms +- [ ] **Documentation**: Update build documentation with asset generation steps +- [ ] **Team Communication**: Communicate asset workflow changes to team diff --git a/.cursor/rules/development/complexity_assessment.mdc b/.cursor/rules/development/complexity_assessment.mdc new file mode 100644 index 00000000..02b97560 --- /dev/null +++ b/.cursor/rules/development/complexity_assessment.mdc @@ -0,0 +1,177 @@ +# Complexity Assessment — Evaluation Frameworks + +> **Agent role**: Reference this file for + complexity evaluation frameworks when assessing project complexity. + +## 📊 Complexity Assessment Framework + +### **Technical Complexity Factors** + +#### **Code Changes** + +- **Simple**: Text, styling, configuration updates + +- **Medium**: New components, refactoring existing code + +- **Complex**: Architecture changes, new patterns, integrations + +- **Unknown**: New technologies, APIs, or approaches + +#### **Platform Impact** + +- **Single platform**: Web-only or mobile-only changes + +- **Two platforms**: Web + mobile or web + desktop + +- **Three platforms**: Web + mobile + desktop + +- **Cross-platform consistency**: Ensuring behavior matches across all platforms + +#### **Testing Requirements** + +- **Basic**: Unit tests for new functionality + +- **Comprehensive**: Integration tests, cross-platform testing + +- **User acceptance**: User testing, feedback integration + +- **Performance**: Load testing, optimization validation + +### **Dependency Complexity** + +#### **Internal Dependencies** + +- **Low**: Self-contained changes, no other components affected + +- **Medium**: Changes affect related components or services + +- **High**: Changes affect core architecture or multiple systems + +- **Critical**: Changes affect data models or core business logic + +#### **External Dependencies** + +- **None**: No external services or APIs involved + +- **Low**: Simple API calls or service integrations + +- **Medium**: Complex integrations with external systems + +- **High**: Third-party platform dependencies or complex APIs + +#### **Infrastructure Dependencies** + +- **None**: No infrastructure changes required + +- **Low**: Configuration updates or environment changes + +- **Medium**: New services or infrastructure components + +- **High**: Platform migrations or major infrastructure changes + +## 🔍 Complexity Evaluation Process + +### **Step 1: Technical Assessment** + +1. **Identify scope of changes** - what files/components are affected + +2. **Assess platform impact** - which platforms need updates + +3. **Evaluate testing needs** - what testing is required + +4. **Consider performance impact** - will this affect performance + +### **Step 2: Dependency Mapping** + +1. **Map internal dependencies** - what other components are affected + +2. **Identify external dependencies** - what external services are involved + +3. **Assess infrastructure needs** - what infrastructure changes are required + +4. **Evaluate risk factors** - what could go wrong + +### **Step 3: Complexity Classification** + +1. **Assign complexity levels** to each factor + +2. **Identify highest complexity** areas that need attention + +3. **Plan mitigation strategies** for high-complexity areas + +4. **Set realistic expectations** based on complexity assessment + +## 📋 Complexity Assessment Checklist + +- [ ] Technical scope identified and mapped + +- [ ] Platform impact assessed across all targets + +- [ ] Testing requirements defined and planned + +- [ ] Internal dependencies mapped and evaluated + +- [ ] External dependencies identified and assessed + +- [ ] Infrastructure requirements evaluated + +- [ ] Risk factors identified and mitigation planned + +- [ ] Complexity levels assigned to all factors + +- [ ] Realistic expectations set based on assessment + +## 🎯 Complexity Reduction Strategies + +### **Scope Reduction** + +- Break large features into smaller, manageable pieces + +- Focus on core functionality first, add polish later + +- Consider phased rollout to reduce initial complexity + +### **Dependency Management** + +- Minimize external dependencies when possible + +- Use abstraction layers to isolate complex integrations + +- Plan for dependency failures and fallbacks + +### **Testing Strategy** + +- Start with basic testing and expand coverage + +- Use automated testing to reduce manual testing complexity + +- Plan for iterative testing and feedback cycles + +## **See also** + +- `.cursor/rules/development/realistic_time_estimation.mdc` for the core principles + +- `.cursor/rules/development/planning_examples.mdc` for planning examples + +## Model Implementation Checklist + +### Before Complexity Assessment + +- [ ] **Problem Scope**: Clearly define the problem to be assessed +- [ ] **Stakeholder Identification**: Identify all parties affected by complexity +- [ ] **Context Analysis**: Understand technical and business context +- [ ] **Assessment Criteria**: Define what factors determine complexity + +### During Complexity Assessment + +- [ ] **Technical Mapping**: Map technical scope and platform impact +- [ ] **Dependency Analysis**: Identify internal and external dependencies +- [ ] **Risk Evaluation**: Assess infrastructure needs and risk factors +- [ ] **Complexity Classification**: Assign complexity levels to all factors + +### After Complexity Assessment + +- [ ] **Mitigation Planning**: Plan strategies for high-complexity areas +- [ ] **Expectation Setting**: Set realistic expectations based on assessment +- [ ] **Documentation**: Document assessment process and findings +- [ ] **Stakeholder Communication**: Share results and recommendations diff --git a/.cursor/rules/development/dependency_management.mdc b/.cursor/rules/development/dependency_management.mdc new file mode 100644 index 00000000..a92f0709 --- /dev/null +++ b/.cursor/rules/development/dependency_management.mdc @@ -0,0 +1,177 @@ +# Dependency Management — Best Practices + +> **Agent role**: Reference this file for dependency management strategies and + best practices when working with software projects. + +## Dependency Management Best Practices + +### Pre-build Validation + +- **Check Critical Dependencies**: + + Validate essential tools before executing build + scripts + +- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to + + avoid PATH issues + +- **Environment Consistency**: Ensure all team members have identical dependency + + versions + +### Common Pitfalls + +- **Missing npm install**: Team members cloning without running `npm install` + +- **PATH Issues**: Direct command execution vs. npm script execution differences + +- **Version Mismatches**: Different Node.js/npm versions across team members + +### Validation Strategies + +- **Dependency Check Scripts**: Implement pre-build validation for critical + + dependencies + +- **Environment Requirements**: + + Document and enforce minimum Node.js/npm versions + +- **Onboarding Checklist**: Standardize team member setup procedures + +### Error Messages and Guidance + +- **Specific Error Context**: + + Provide clear guidance when dependency issues occur + +- **Actionable Solutions**: Direct users to specific commands (`npm install`, + + `npm run check:dependencies`) + +- **Environment Diagnostics**: Implement comprehensive environment validation + + tools + +### Build Script Enhancements + +- **Early Validation**: Check dependencies before starting build processes + +- **Graceful Degradation**: Continue builds when possible but warn about issues + +- **Helpful Tips**: Remind users about dependency management best practices + +## Environment Setup Guidelines + +### Required Tools + +- **Node.js**: Minimum version requirements and LTS recommendations + +- **npm**: Version compatibility and global package management + +- **Platform-specific tools**: Android SDK, Xcode, etc. + +### Environment Variables + +- **NODE_ENV**: Development, testing, production environments + +- **PATH**: Ensure tools are accessible from command line + +- **Platform-specific**: Android SDK paths, Xcode command line tools + +### Validation Commands + +```bash + +# Check Node.js version + +node --version + +# Check npm version + +npm --version + +# Check global packages + +npm list -g --depth=0 + +# Validate platform tools + +npx capacitor doctor + +``` + +## Dependency Troubleshooting + +### Common Issues + +1. **Permission Errors**: Use `sudo` sparingly, prefer `npm config set prefix` + +2. **Version Conflicts**: Use `npm ls` to identify dependency conflicts + +3. **Cache Issues**: Clear npm cache with `npm cache clean --force` + +4. **Lock File Issues**: Delete `package-lock.json` and `node_modules`, + + then reinstall + +### Resolution Strategies + +- **Dependency Audit**: Run `npm audit` to identify security issues + +- **Version Pinning**: Use exact versions for critical dependencies + +- **Peer Dependency Management**: Ensure compatible versions across packages + +- **Platform-specific Dependencies**: Handle different requirements per platform + +## Best Practices for Teams + +### Onboarding + +- **Environment Setup Script**: Automated setup for new team members + +- **Version Locking**: Use `package-lock.json` and `yarn.lock` consistently + +- **Documentation**: Clear setup instructions with troubleshooting steps + +### Maintenance + +- **Regular Updates**: Schedule dependency updates and security patches + +- **Testing**: Validate changes don't break existing functionality + +- **Rollback Plan**: Maintain ability to revert to previous working versions + +**See also**: + `.cursor/rules/development/software_development.mdc` for core development principles. + +**Status**: Active dependency management guidelines +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: software_development.mdc +**Stakeholders**: Development team, DevOps team + +## Model Implementation Checklist + +### Before Dependency Changes + +- [ ] **Current State Review**: Check current dependency versions and status +- [ ] **Impact Analysis**: Assess impact of dependency changes on codebase +- [ ] **Compatibility Check**: Verify compatibility with existing code +- [ ] **Security Review**: Review security implications of dependency changes + +### During Dependency Management + +- [ ] **Version Selection**: Choose appropriate dependency versions +- [ ] **Testing**: Test with new dependency versions +- [ ] **Documentation**: Update dependency documentation +- [ ] **Team Communication**: Communicate changes to team members + +### After Dependency Changes + +- [ ] **Comprehensive Testing**: Test all functionality with new dependencies +- [ ] **Documentation Update**: Update all relevant documentation +- [ ] **Deployment Planning**: Plan and execute deployment strategy +- [ ] **Monitoring**: Monitor for issues after deployment diff --git a/.cursor/rules/development/development_guide.mdc b/.cursor/rules/development/development_guide.mdc index 439c1f26..092ffb98 100644 --- a/.cursor/rules/development/development_guide.mdc +++ b/.cursor/rules/development/development_guide.mdc @@ -2,8 +2,32 @@ globs: **/src/**/* alwaysApply: false --- -✅ use system date command to timestamp all interactions with accurate date and time +✅ 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 ✅ remove whitespace at the end of lines ✅ use npm run lint-fix to check for warnings ✅ do not use npm run dev let me handle running and supplying feedback + +## Model Implementation Checklist + +### Before Development Work + +- [ ] **System Date Check**: Use system date command for accurate timestamps +- [ ] **Environment Setup**: Verify development environment is ready +- [ ] **Linting Setup**: Ensure npm run lint-fix is available +- [ ] **Code Standards**: Review project coding standards and requirements + +### During Development + +- [ ] **Timestamp Usage**: Include accurate timestamps in all interactions +- [ ] **Code Quality**: Use npm run lint-fix to check for warnings +- [ ] **File Standards**: Ensure Python files have blank line at end +- [ ] **Whitespace**: Remove trailing whitespace from all lines + +### After Development + +- [ ] **Linting Check**: Run npm run lint-fix to verify code quality +- [ ] **File Validation**: Confirm Python files end with blank line +- [ ] **Whitespace Review**: Verify no trailing whitespace remains +- [ ] **Documentation**: Update relevant documentation with changes diff --git a/.cursor/rules/development/historical_comment_management.mdc b/.cursor/rules/development/historical_comment_management.mdc new file mode 100644 index 00000000..9634e9d0 --- /dev/null +++ b/.cursor/rules/development/historical_comment_management.mdc @@ -0,0 +1,119 @@ +# Historical Comment Management — Code Clarity Guidelines + +> **Agent role**: When encountering historical comments about removed +> methods, deprecated patterns, or architectural changes, apply these +> guidelines to maintain code clarity and developer guidance. + +## Overview + +Historical comments should either be **removed entirely** or **transformed +into actionable guidance** for future developers. Avoid keeping comments +that merely state what was removed without explaining why or what to do +instead. + +## Decision Framework + +### When to Remove Comments + +- **Obsolete Information**: Comment describes functionality that no + longer exists +- **Outdated Context**: Comment refers to old patterns that are no + longer relevant +- **No Actionable Value**: Comment doesn't help future developers + make decisions + +### When to Transform Comments + +- **Migration Guidance**: Future developers might need to understand + the evolution +- **Alternative Approaches**: The comment can guide future + implementation choices +- **Historical Context**: Understanding the change helps with + current decisions + +## Transformation Patterns + +### 1. **Removed Method** → **Alternative Approach** + +```typescript +// Before: Historical comment +// turnOffNotifyingFlags method removed - notification state is now +// managed by NotificationSection component + +// After: Actionable guidance +// Note: Notification state management has been migrated to +// NotificationSection component +``` + +### 2. **Deprecated Pattern** → **Current Best Practice** + +```typescript +// Before: Historical comment +// Database access has been migrated from direct IndexedDB calls to +// PlatformServiceMixin + +// After: Actionable guidance +// This provides better platform abstraction and consistent error +// handling across web/mobile/desktop + +// When adding new database operations, use this.$getContact(), +// this.$saveSettings(), etc. +``` + +## Best Practices + +### 1. **Use Actionable Language**: Guide future decisions, not just + +document history + +### 2. **Provide Alternatives**: Always suggest what to use instead + +### 3. **Update Related Docs**: If removing from code, consider + +adding to documentation + +### 4. **Keep Context**: Include enough information to understand + +why the change was made + +## Integration Points + +- Apply these rules when reviewing code changes +- Use during code cleanup and refactoring +- Include in code review checklists + +--- + +**See also**: + +- `.cursor/rules/development/historical_comment_patterns.mdc` for detailed + transformation examples and patterns + +**Status**: Active comment management guidelines +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Code reviewers + +## Model Implementation Checklist + +### Before Comment Review + +- [ ] **Code Analysis**: Review code for historical or outdated comments +- [ ] **Context Understanding**: Understand the current state of the codebase +- [ ] **Pattern Identification**: Identify comments that need transformation or removal +- [ ] **Documentation Planning**: Plan where to move important historical context + +### During Comment Management + +- [ ] **Transformation**: Convert historical comments to actionable guidance +- [ ] **Alternative Provision**: Suggest current best practices and alternatives +- [ ] **Context Preservation**: Maintain enough information to understand changes +- [ ] **Documentation Update**: Move important context to appropriate documentation + +### After Comment Management + +- [ ] **Code Review**: Ensure transformed comments provide actionable value +- [ ] **Documentation Sync**: Verify related documentation is updated +- [ ] **Team Communication**: Share comment transformation patterns with team +- [ ] **Process Integration**: Include comment management in code review checklists diff --git a/.cursor/rules/development/historical_comment_patterns.mdc b/.cursor/rules/development/historical_comment_patterns.mdc new file mode 100644 index 00000000..47dc60bb --- /dev/null +++ b/.cursor/rules/development/historical_comment_patterns.mdc @@ -0,0 +1,139 @@ +# Historical Comment Patterns — Transformation Examples + +> **Agent role**: Reference this file for specific patterns and + examples when transforming historical comments into actionable guidance. + +## 🔄 Transformation Patterns + +### 1. From Removal Notice to Migration Note + +```typescript + +// ❌ REMOVE THIS +// turnOffNotifyingFlags method removed - + notification state is now managed by NotificationSection component + +// ✅ TRANSFORM TO THIS +// Note: Notification state management has been migrated to NotificationSection + component +// which handles its own lifecycle and persistence via PlatformServiceMixin + +``` + +### 2. From Deprecation Notice to Implementation Guide + +```typescript + +// ❌ REMOVE THIS +// This will be handled by the NewComponent now +// No need to call oldMethod() as it's no longer needed + +// ✅ TRANSFORM TO THIS +// Note: This functionality has been migrated to NewComponent +// which provides better separation of concerns and testability + +``` + +### 3. From Historical Note to Architectural Context + +```typescript + +// ❌ REMOVE THIS +// Old approach: used direct database calls +// New approach: uses service layer + +// ✅ TRANSFORM TO THIS +// Note: Database access has been abstracted through service layer +// for better testability and platform independence + +``` + +## 🚫 Anti-Patterns to Remove + +- Comments that only state what was removed + +- Comments that don't explain the current approach + +- Comments that reference non-existent methods + +- Comments that are self-evident from the code + +- Comments that don't help future decision-making + +## 📚 Examples + +### Good Historical Comment (Keep & Transform) + +```typescript + +// Note: Database access has been migrated from direct IndexedDB calls to + PlatformServiceMixin +// This provides better platform abstraction and + consistent error handling across web/mobile/desktop +// When adding new database operations, use this.$getContact(), + this.$saveSettings(), etc. + +``` + +### Bad Historical Comment (Remove) + +```typescript + +// Old method getContactFromDB() removed - now handled by PlatformServiceMixin +// No need to call the old method anymore + +``` + +## 🎯 When to Use Each Pattern + +### Migration Notes + +- Use when functionality has moved to a different component/service + +- Explain the new location and why it's better + +- Provide guidance on how to use the new approach + +### Implementation Guides + +- Use when patterns have changed significantly + +- Explain the architectural benefits + +- Show how to implement the new pattern + +### Architectural Context + +- Use when the change represents a system-wide improvement + +- Explain the reasoning behind the change + +- Help future developers understand the evolution + +--- + +**See also**: `.cursor/rules/development/historical_comment_management.mdc` for + the core decision framework and best practices. + +## Model Implementation Checklist + +### Before Comment Review + +- [ ] **Code Analysis**: Review code for historical or outdated comments +- [ ] **Pattern Identification**: Identify comments that need transformation or removal +- [ ] **Context Understanding**: Understand the current state of the codebase +- [ ] **Transformation Planning**: Plan how to transform or remove comments + +### During Comment Transformation + +- [ ] **Pattern Selection**: Choose appropriate transformation pattern +- [ ] **Content Creation**: Create actionable guidance for future developers +- [ ] **Alternative Provision**: Suggest current best practices and approaches +- [ ] **Context Preservation**: Maintain enough information to understand changes + +### After Comment Transformation + +- [ ] **Code Review**: Ensure transformed comments provide actionable value +- [ ] **Pattern Documentation**: Document transformation patterns for team use +- [ ] **Team Communication**: Share comment transformation patterns with team +- [ ] **Process Integration**: Include comment patterns in code review checklists diff --git a/.cursor/rules/investigation_report_example.mdc b/.cursor/rules/development/investigation_report_example.mdc similarity index 78% rename from .cursor/rules/investigation_report_example.mdc rename to .cursor/rules/development/investigation_report_example.mdc index ca3a7d36..8014105c 100644 --- a/.cursor/rules/investigation_report_example.mdc +++ b/.cursor/rules/development/investigation_report_example.mdc @@ -14,70 +14,100 @@ import scenarios. ## System Map - User action → ContactInputForm → ContactsView.addContact() → + handleRegistrationPrompt() + - setTimeout(1000ms) → Modal dialog → User response → Registration API call + - Test execution → Wait for dialog → Assert dialog content → Click response + button ## Findings (Evidence) - **1-second timeout causes flakiness** — evidence: + `src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in handleRegistrationPrompt() + - **Import flow bypasses dialogs** — evidence: + `src/views/ContactImportView.vue:500-520`; importContacts() calls $insertContact() directly, no handleRegistrationPrompt() + - **Dialog only appears in direct add flow** — evidence: + `src/views/ContactsView.vue:774-800`; addContact() calls handleRegistrationPrompt() after database insert ## Hypotheses & Failure Modes - H1: 1-second timeout makes dialog appearance unpredictable; would fail when + tests run faster than 1000ms + - H2: Test environment timing differs from development; watch for CI vs local + test differences ## Corrections - Updated: "Multiple dialogs interfere with imports" → "Import flow never + triggers dialogs - they only appear in direct contact addition" + - Updated: "Complex batch registration needed" → "Simple timeout removal and + test mode flag sufficient" ## Diagnostics (Next Checks) - [ ] Repro on CI environment vs local + - [ ] Measure actual dialog appearance timing + - [ ] Test with setTimeout removed + - [ ] Verify import flow doesn't call handleRegistrationPrompt ## Risks & Scope - Impacted: Contact addition tests, registration workflow tests; Data: None; + Users: Test suite reliability ## Decision / Next Steps - Owner: Development Team; By: 2025-01-28 + - Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests + pass consistently ## References - `src/views/ContactsView.vue:971-1000` + - `src/views/ContactImportView.vue:500-520` + - `src/views/ContactsView.vue:774-800` ## Competence Hooks - Why this works: Code path tracing revealed separate execution flows, + evidence disproved initial assumptions + - Common pitfalls: Assuming related functionality without tracing execution + paths, over-engineering solutions to imaginary problems + - Next skill: Learn to trace code execution before proposing architectural + changes + - Teach-back: "What evidence shows that contact imports bypass registration + dialogs?" ## Key Learning Points @@ -87,8 +117,11 @@ import scenarios. This investigation demonstrates the importance of: 1. **Tracing actual code execution** rather than making assumptions + 2. **Citing specific evidence** with file:line references + 3. **Validating problem scope** before proposing solutions + 4. **Considering simpler alternatives** before complex architectural changes ### Code Path Tracing Value @@ -96,7 +129,9 @@ This investigation demonstrates the importance of: By tracing the execution paths, we discovered: - Import flow and direct add flow are completely separate + - The "multiple dialog interference" problem didn't exist + - A simple timeout removal would solve the actual issue ### Prevention of Over-Engineering @@ -104,8 +139,11 @@ By tracing the execution paths, we discovered: The investigation prevented: - Unnecessary database schema changes + - Complex batch registration systems + - Migration scripts for non-existent problems + - Architectural changes based on assumptions --- @@ -115,3 +153,26 @@ The investigation prevented: **Estimated Effort**: Ongoing reference **Dependencies**: software_development.mdc **Stakeholders**: Development team, QA team + +## Model Implementation Checklist + +### Before Investigation + +- [ ] **Problem Definition**: Clearly define the problem to investigate +- [ ] **Scope Definition**: Determine investigation scope and boundaries +- [ ] **Methodology Planning**: Plan investigation approach and methods +- [ ] **Resource Assessment**: Identify required resources and tools + +### During Investigation + +- [ ] **Evidence Collection**: Gather relevant evidence and data systematically +- [ ] **Code Path Tracing**: Map execution flow for software investigations +- [ ] **Analysis**: Analyze evidence using appropriate methods +- [ ] **Documentation**: Document investigation process and findings + +### After Investigation + +- [ ] **Synthesis**: Synthesize findings into actionable insights +- [ ] **Report Creation**: Create comprehensive investigation report +- [ ] **Recommendations**: Provide clear, actionable recommendations +- [ ] **Team Communication**: Share findings and next steps with team diff --git a/.cursor/rules/development/logging_migration.mdc b/.cursor/rules/development/logging_migration.mdc new file mode 100644 index 00000000..bbb0c97d --- /dev/null +++ b/.cursor/rules/development/logging_migration.mdc @@ -0,0 +1,358 @@ +--- +alwaysApply: false +--- + +# Logging Migration — Patterns and Examples + +> **Agent role**: Reference this file for specific migration patterns and + examples when converting console.* calls to logger usage. + +## Migration — Auto‑Rewrites (Apply Every Time) + +### Exact Transforms + +- `console.debug(...)` → `logger.debug(...)` + +- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when + + clearly stateful) + +- `console.info(...)` → `logger.info(...)` + +- `console.warn(...)` → `logger.warn(...)` + +- `console.error(...)` → `logger.error(...)` + +### Multi-arg Handling + +- First arg becomes `message` (stringify safely if non-string). + +- Remaining args map 1:1 to `...args`: + + `console.info(msg, a, b)` → `logger.info(String(msg), a, b)` + +### Sole `Error` + +- `console.error(err)` → `logger.error(err.message, err)` + +### Object-wrapping Cleanup + +Replace `{{ userId, meta }}` wrappers with separate args: +`logger.info('User signed in', userId, meta)` + +## Level Guidelines with Examples + +### DEBUG Examples + +```typescript + +logger.debug('[HomeView] reloadFeedOnChange() called'); +logger.debug('[HomeView] Current filter settings', + settings.filterFeedByVisible, + settings.filterFeedByNearby, + settings.searchBoxes?.length ?? 0); +logger.debug('[FeedFilters] Toggling nearby filter', + this.isNearby, this.settingChanged, this.activeDid); + +``` + +**Avoid**: Vague messages (`'Processing data'`). + +### INFO Examples + +```typescript + +logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); +logger.info('[StartView] User selected new seed generation'); +logger.info('[SearchAreaView] Search box stored', + searchBox.name, searchBox.bbox); +logger.info('[ContactQRScanShowView] Contact registration OK', + contact.did); + +``` + +**Avoid**: Diagnostic details that belong in `debug`. + +### WARN Examples + +```typescript + +logger.warn('[ContactQRScanShowView] Invalid scan result – no value', + resultType); +logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); +logger.warn('[ContactQRScanShowView] JWT missing "own" field'); + +``` + +**Avoid**: Hard failures (those are `error`). + +### ERROR Examples + +```typescript + +logger.error('[HomeView Settings] initializeIdentity() failed', err); +logger.error('[StartView] Failed to load initialization data', error); +logger.error('[ContactQRScanShowView] Error processing contact QR', + error, rawValue); + +``` + +**Avoid**: Expected user cancels (use `info`/`debug`). + +## Context Hygiene Examples + +### Component Context + +```typescript + +const log = logger.withContext('UserService'); +log.info('User created', userId); +log.error('Failed to create user', error); + +``` + +If not using `withContext`, prefix message with `[ComponentName]`. + +### Emoji Guidelines + +Recommended set for visual scanning: + +- Start/finish: 🚀 / ✅ + +- Retry/loop: 🔄 + +- External call: 📡 + +- Data/metrics: 📊 + +- Inspection: 🔍 + +## Quick Before/After + +### **Before** + +```typescript + +console.log('User signed in', user.id, meta); +console.error('Failed to update profile', err); +console.info('Filter toggled', this.hasVisibleDid); + +``` + +### **After** + +```typescript + +import { logger } from '@/utils/logger'; + +logger.info('User signed in', user.id, meta); +logger.error('Failed to update profile', err); +logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); + +``` + +## Checklist (for every PR) + +- [ ] No `console.*` (or properly pragma'd in the allowed locations) + +- [ ] Correct import path for `logger` + +- [ ] Rest-parameter call shape (`message, ...args`) + +- [ ] Right level chosen (debug/info/warn/error) + +- [ ] No secrets / oversized payloads / throwaway context objects + +- [ ] Component context provided (scoped logger or `[Component]` prefix) + +**See also**: + `.cursor/rules/development/logging_standards.mdc` for the core standards and rules. + +# Logging Migration — Patterns and Examples + +> **Agent role**: Reference this file for specific migration patterns and + examples when converting console.* calls to logger usage. + +## Migration — Auto‑Rewrites (Apply Every Time) + +### Exact Transforms + +- `console.debug(...)` → `logger.debug(...)` + +- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when + + clearly stateful) + +- `console.info(...)` → `logger.info(...)` + +- `console.warn(...)` → `logger.warn(...)` + +- `console.error(...)` → `logger.error(...)` + +### Multi-arg Handling + +- First arg becomes `message` (stringify safely if non-string). + +- Remaining args map 1:1 to `...args`: + + `console.info(msg, a, b)` → `logger.info(String(msg), a, b)` + +### Sole `Error` + +- `console.error(err)` → `logger.error(err.message, err)` + +### Object-wrapping Cleanup + +Replace `{{ userId, meta }}` wrappers with separate args: +`logger.info('User signed in', userId, meta)` + +## Level Guidelines with Examples + +### DEBUG Examples + +```typescript + +logger.debug('[HomeView] reloadFeedOnChange() called'); +logger.debug('[HomeView] Current filter settings', + settings.filterFeedByVisible, + settings.filterFeedByNearby, + settings.searchBoxes?.length ?? 0); +logger.debug('[FeedFilters] Toggling nearby filter', + this.isNearby, this.settingChanged, this.activeDid); + +``` + +**Avoid**: Vague messages (`'Processing data'`). + +### INFO Examples + +```typescript + +logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); +logger.info('[StartView] User selected new seed generation'); +logger.info('[SearchAreaView] Search box stored', + searchBox.name, searchBox.bbox); +logger.info('[ContactQRScanShowView] Contact registration OK', + contact.did); + +``` + +**Avoid**: Diagnostic details that belong in `debug`. + +### WARN Examples + +```typescript + +logger.warn('[ContactQRScanShowView] Invalid scan result – no value', + resultType); +logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); +logger.warn('[ContactQRScanShowView] JWT missing "own" field'); + +``` + +**Avoid**: Hard failures (those are `error`). + +### ERROR Examples + +```typescript + +logger.error('[HomeView Settings] initializeIdentity() failed', err); +logger.error('[StartView] Failed to load initialization data', error); +logger.error('[ContactQRScanShowView] Error processing contact QR', + error, rawValue); + +``` + +**Avoid**: Expected user cancels (use `info`/`debug`). + +## Context Hygiene Examples + +### Component Context + +```typescript + +const log = logger.withContext('UserService'); +log.info('User created', userId); +log.error('Failed to create user', error); + +``` + +If not using `withContext`, prefix message with `[ComponentName]`. + +### Emoji Guidelines + +Recommended set for visual scanning: + +- Start/finish: 🚀 / ✅ + +- Retry/loop: 🔄 + +- External call: 📡 + +- Data/metrics: 📊 + +- Inspection: 🔍 + +## Quick Before/After + +### **Before** + +```typescript + +console.log('User signed in', user.id, meta); +console.error('Failed to update profile', err); +console.info('Filter toggled', this.hasVisibleDid); + +``` + +### **After** + +```typescript + +import { logger } from '@/utils/logger'; + +logger.info('User signed in', user.id, meta); +logger.error('Failed to update profile', err); +logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); + +``` + +## Checklist (for every PR) + +- [ ] No `console.*` (or properly pragma'd in the allowed locations) + +- [ ] Correct import path for `logger` + +- [ ] Rest-parameter call shape (`message, ...args`) + +- [ ] Right level chosen (debug/info/warn/error) + +- [ ] No secrets / oversized payloads / throwaway context objects + +- [ ] Component context provided (scoped logger or `[Component]` prefix) + +**See also**: + `.cursor/rules/development/logging_standards.mdc` for the core standards and rules. + +## Model Implementation Checklist + +### Before Logging Migration + +- [ ] **Code Review**: Identify all `console.*` calls in the codebase +- [ ] **Logger Import**: Verify logger utility is available and accessible +- [ ] **Context Planning**: Plan component context for each logging call +- [ ] **Level Assessment**: Determine appropriate log levels for each call + +### During Logging Migration + +- [ ] **Import Replacement**: Replace `console.*` with `logger.*` calls +- [ ] **Context Addition**: Add component context using scoped logger or prefix +- [ ] **Level Selection**: Choose appropriate log level (debug/info/warn/error) +- [ ] **Parameter Format**: Use rest-parameter call shape (`message, ...args`) + +### After Logging Migration + +- [ ] **Console Check**: Ensure no `console.*` methods remain (unless pragma'd) +- [ ] **Context Validation**: Verify all logging calls have proper context +- [ ] **Level Review**: Confirm log levels are appropriate for each situation +- [ ] **Testing**: Test logging functionality across all platforms diff --git a/.cursor/rules/logging_standards.mdc b/.cursor/rules/development/logging_standards.mdc similarity index 52% rename from .cursor/rules/logging_standards.mdc rename to .cursor/rules/development/logging_standards.mdc index 2b9d6507..5086567a 100644 --- a/.cursor/rules/logging_standards.mdc +++ b/.cursor/rules/development/logging_standards.mdc @@ -21,29 +21,49 @@ logger; no `console.*` in production code. ## Non‑Negotiables (DO THIS) - You **MUST** use the project logger; **DO NOT** use any `console.*` + methods. + - Import exactly as: + - `import { logger } from '@/utils/logger'` + - If `@` alias is unavailable, compute the correct relative path (do not + fail). + - Call signatures use **rest parameters**: `logger.info(message, ...args)` + - Prefer primitives/IDs and small objects in `...args`; **never build a + throwaway object** just to "wrap context". + - Production defaults: Web = `warn+`, Electron = `error`, Dev/Capacitor = + `info+` (override via `VITE_LOG_LEVEL`). + - **Database persistence**: `info|warn|error` are persisted; `debug` is not. + Use `logger.toDb(msg, level?)` for DB-only. ## Available Logger API (Authoritative) - `logger.debug(message, ...args)` — verbose internals, timings, input/output + shapes + - `logger.log(message, ...args)` — synonym of `info` for general info + - `logger.info(message, ...args)` — lifecycle, state changes, success paths + - `logger.warn(message, ...args)` — recoverable issues, retries, degraded mode + - `logger.error(message, ...args)` — failures, thrown exceptions, aborts + - `logger.toDb(message, level?)` — DB-only entry (default level = `info`) + - `logger.toConsoleAndDb(message, isError)` — console + DB (use sparingly) + - `logger.withContext(componentName)` — returns a scoped logger ## Level Guidelines (Use These Heuristics) @@ -53,108 +73,34 @@ logger; no `console.*` in production code. Use for method entry/exit, computed values, filters, loops, retries, and external call payload sizes. -```typescript -logger.debug('[HomeView] reloadFeedOnChange() called'); -logger.debug('[HomeView] Current filter settings', - settings.filterFeedByVisible, - settings.filterFeedByNearby, - settings.searchBoxes?.length ?? 0); -logger.debug('[FeedFilters] Toggling nearby filter', - this.isNearby, this.settingChanged, this.activeDid); -``` - -**Avoid**: Vague messages (`'Processing data'`). - ### INFO Use for user-visible lifecycle and completed operations. -```typescript -logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM); -logger.info('[StartView] User selected new seed generation'); -logger.info('[SearchAreaView] Search box stored', - searchBox.name, searchBox.bbox); -logger.info('[ContactQRScanShowView] Contact registration OK', - contact.did); -``` - -**Avoid**: Diagnostic details that belong in `debug`. - ### WARN Use for recoverable issues, fallbacks, unexpected-but-handled conditions. -```typescript -logger.warn('[ContactQRScanShowView] Invalid scan result – no value', - resultType); -logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL'); -logger.warn('[ContactQRScanShowView] JWT missing "own" field'); -``` - -**Avoid**: Hard failures (those are `error`). - ### ERROR Use for unrecoverable failures, data integrity issues, and thrown exceptions. -```typescript -logger.error('[HomeView Settings] initializeIdentity() failed', err); -logger.error('[StartView] Failed to load initialization data', error); -logger.error('[ContactQRScanShowView] Error processing contact QR', - error, rawValue); -``` - -**Avoid**: Expected user cancels (use `info`/`debug`). - ## Context Hygiene (Consistent, Minimal, Helpful) - **Component context**: Prefer scoped logger. -```typescript -const log = logger.withContext('UserService'); -log.info('User created', userId); -log.error('Failed to create user', error); -``` - -If not using `withContext`, prefix message with `[ComponentName]`. - -- **Emojis**: Optional and minimal for visual scanning. Recommended set: - - Start/finish: 🚀 / ✅ - - Retry/loop: 🔄 - - External call: 📡 - - Data/metrics: 📊 - - Inspection: 🔍 +- **Emojis**: Optional and minimal for visual scanning. - **Sensitive data**: Never log secrets (tokens, keys, passwords) or payloads >10KB. Prefer IDs over objects; redact/hash when needed. -## Migration — Auto‑Rewrites (Apply Every Time) - -- Exact transforms: - - `console.debug(...)` → `logger.debug(...)` - - `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when - clearly stateful) - - `console.info(...)` → `logger.info(...)` - - `console.warn(...)` → `logger.warn(...)` - - `console.error(...)` → `logger.error(...)` - -- Multi-arg handling: - - First arg becomes `message` (stringify safely if non-string). - - Remaining args map 1:1 to `...args`: - `console.info(msg, a, b)` → `logger.info(String(msg), a, b)` - -- Sole `Error`: - - `console.error(err)` → `logger.error(err.message, err)` - -- **Object-wrapping cleanup**: Replace `{{ userId, meta }}` wrappers with - separate args: - `logger.info('User signed in', userId, meta)` - ## DB Logging Rules - `debug` **never** persists automatically. + - `info|warn|error` persist automatically. + - For DB-only events (no console), call `logger.toDb('Message', 'info'|'warn'|'error')`. @@ -163,60 +109,68 @@ If not using `withContext`, prefix message with `[ComponentName]`. Allowed paths (still prefer logger): - `**/*.test.*`, `**/*.spec.*` + - `scripts/dev/**`, `scripts/migrate/**` To intentionally keep `console.*`, add a pragma on the previous line: ```typescript + // cursor:allow-console reason="short justification" console.log('temporary output'); -``` -Without the pragma, rewrite to `logger.*`. +``` ## CI & Diff Enforcement - Do not introduce `console.*` anywhere outside allowed, pragma'd spots. + - If an import is missing, insert it and resolve alias/relative path correctly. + - Enforce rest-parameter call shape in reviews; replace object-wrapped context. + - Ensure environment log level rules remain intact (`VITE_LOG_LEVEL` respected). -## Quick Before/After +--- -### **Before** +**See also**: + `.cursor/rules/development/logging_migration.mdc` for migration patterns and examples. -```typescript -console.log('User signed in', user.id, meta); -console.error('Failed to update profile', err); -console.info('Filter toggled', this.hasVisibleDid); -``` +**Status**: Active and enforced +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: TimeSafari logger utility +**Stakeholders**: Development team, Code review team -### **After** +## Model Implementation Checklist -```typescript -import { logger } from '@/utils/logger'; +### Before Adding Logging -logger.info('User signed in', user.id, meta); -logger.error('Failed to update profile', err); -logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid); -``` +- [ ] **Logger Import**: Import logger as `import { logger } from + '@/utils/logger'` +- [ ] **Log Level Selection**: Determine appropriate log level + (debug/info/warn/error) +- [ ] **Context Planning**: Plan what context information to include +- [ ] **Sensitive Data Review**: Identify any sensitive data that needs redaction -## Checklist (for every PR) +### During Logging Implementation -- [ ] No `console.*` (or properly pragma'd in the allowed locations) -- [ ] Correct import path for `logger` -- [ ] Rest-parameter call shape (`message, ...args`) -- [ ] Right level chosen (debug/info/warn/error) -- [ ] No secrets / oversized payloads / throwaway context objects -- [ ] Component context provided (scoped logger or `[Component]` prefix) +- [ ] **Rest Parameters**: Use `logger.info(message, ...args)` format, not object + wrapping +- [ ] **Context Addition**: Include relevant IDs, primitives, or small objects in + args +- [ ] **Level Appropriateness**: Use correct log level for the situation +- [ ] **Scoped Logger**: Use `logger.withContext(componentName)` for + component-specific logging ---- +### After Logging Implementation -**Status**: Active and enforced -**Priority**: Critical -**Estimated Effort**: Ongoing reference -**Dependencies**: TimeSafari logger utility -**Stakeholders**: Development team, Code review team +- [ ] **Console Check**: Ensure no `console.*` methods are used (unless in + allowed paths) +- [ ] **Performance Review**: Verify logging doesn't impact performance +- [ ] **DB Persistence**: Use `logger.toDb()` for database-only logging if needed +- [ ] **Environment Compliance**: Respect `VITE_LOG_LEVEL` environment + variable diff --git a/.cursor/rules/development/planning_examples.mdc b/.cursor/rules/development/planning_examples.mdc new file mode 100644 index 00000000..310d73cd --- /dev/null +++ b/.cursor/rules/development/planning_examples.mdc @@ -0,0 +1,160 @@ +# Planning Examples — No Time Estimates + +> **Agent role**: Reference this file for detailed planning examples and + anti-patterns when creating project plans. + +## 🎯 Example Planning (No Time Estimates) + +### **Example 1: Simple Feature** + +``` + +Phase 1: Core implementation + +- Basic functionality + +- Single platform support + +- Unit tests + +Phase 2: Platform expansion + +- Multi-platform support + +- Integration tests + +Phase 3: Polish + +- User testing + +- Edge case handling + +``` + +### **Example 2: Complex Cross-Platform Feature** + +``` + +Phase 1: Foundation + +- Architecture design + +- Core service implementation + +- Basic web platform support + +Phase 2: Platform Integration + +- Mobile platform support + +- Desktop platform support + +- Cross-platform consistency + +Phase 3: Testing & Polish + +- Comprehensive testing + +- Error handling + +- User experience refinement + +``` + +## 🚫 Anti-Patterns to Avoid + +- **"This should take X days"** - Red flag for time estimation + +- **"Just a few hours"** - Ignores complexity and testing + +- **"Similar to X"** - Without considering differences + +- **"Quick fix"** - Nothing is ever quick in software + +- **"No testing needed"** - Testing always takes effort + +## ✅ Best Practices + +### **When Planning:** + +1. **Break down everything** - no work is too small to plan + +2. **Consider all platforms** - web, mobile, desktop differences + +3. **Include testing strategy** - unit, integration, and user testing + +4. **Account for unknowns** - there are always surprises + +5. **Focus on dependencies** - what blocks what + +### **When Presenting Plans:** + +1. **Show the phases** - explain the logical progression + +2. **Highlight dependencies** - what could block progress + +3. **Define milestones** - clear success criteria + +4. **Identify risks** - what could go wrong + +5. **Suggest alternatives** - ways to reduce scope or complexity + +## 🔄 Continuous Improvement + +### **Track Progress** + +- Record planned vs. actual phases completed + +- Identify what took longer than expected + +- Learn from complexity misjudgments + +- Adjust planning process based on experience + +### **Learn from Experience** + +- **Underestimated complexity**: Increase complexity categories + +- **Missed dependencies**: Improve dependency mapping + +- **Platform surprises**: Better platform research upfront + +## 🎯 Integration with Harbor Pilot + +This rule works in conjunction with: + +- **Project Planning**: Focuses on phases and milestones + +- **Resource Allocation**: Based on complexity, not time + +- **Risk Management**: Identifies blockers and dependencies + +- **Stakeholder Communication**: Sets progress-based expectations + +--- + +**See also**: `.cursor/rules/development/realistic_time_estimation.mdc` for + the core principles and framework. + +## Model Implementation Checklist + +### Before Planning + +- [ ] **Requirements Review**: Understand all requirements completely +- [ ] **Stakeholder Input**: Gather input from all stakeholders +- [ ] **Complexity Assessment**: Evaluate technical and business complexity +- [ ] **Platform Analysis**: Consider requirements across all target platforms + +### During Planning + +- [ ] **Phase Definition**: Define clear phases and milestones +- [ ] **Dependency Mapping**: Map dependencies between tasks +- [ ] **Risk Identification**: Identify potential risks and challenges +- [ ] **Testing Strategy**: Plan comprehensive testing approach + +### After Planning + +- [ ] **Stakeholder Review**: Review plan with stakeholders +- [ ] **Documentation**: Document plan clearly with phases and milestones +- [ ] **Team Communication**: Communicate plan to team +- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms diff --git a/.cursor/rules/development/realistic_time_estimation.mdc b/.cursor/rules/development/realistic_time_estimation.mdc new file mode 100644 index 00000000..f08a4398 --- /dev/null +++ b/.cursor/rules/development/realistic_time_estimation.mdc @@ -0,0 +1,128 @@ +# Realistic Time Estimation — Development Guidelines + +> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, +> milestones, and complexity levels. Time estimates are consistently wrong +> and create unrealistic expectations. + +## Purpose + +Development time estimates are consistently wrong and create unrealistic +expectations. This rule ensures we focus on phases, milestones, and +complexity rather than trying to predict specific timeframes. + +## Critical Rule + +**NEVER provide specific time estimates** (hours, days, weeks) for +development tasks. Instead, use: + +- **Complexity levels** (Low, Medium, High, Critical) + +- **Phases and milestones** with clear acceptance criteria + +- **Platform-specific considerations** (Web, Mobile, Desktop) + +- **Testing requirements** and validation steps + +## Planning Framework + +### Complexity Assessment + +- **Low**: Simple changes, existing patterns, minimal testing + +- **Medium**: New features, moderate testing, some integration + +- **High**: Complex features, extensive testing, multiple platforms + +- **Critical**: Core architecture changes, full regression testing + +### Platform Categories + +- **Web**: Browser compatibility, responsive design, accessibility + +- **Mobile**: Native APIs, platform-specific testing, deployment + +- **Desktop**: Electron integration, system APIs, distribution + +### Testing Strategy + +- **Unit tests**: Core functionality validation + +- **Integration tests**: Component interaction testing + +- **E2E tests**: User workflow validation + +- **Platform tests**: Cross-platform compatibility + +## Process Guidelines + +### Planning Phase + +1. **Scope Definition**: Clear requirements and acceptance criteria + +2. **Complexity Assessment**: Evaluate technical and business complexity + +3. **Phase Breakdown**: Divide into logical, testable phases + +4. **Milestone Definition**: Define success criteria for each phase + +### Execution Phase + +1. **Phase 1**: Foundation and core implementation + +2. **Phase 2**: Feature completion and integration + +3. **Phase 3**: Testing, refinement, and documentation + +4. **Phase 4**: Deployment and validation + +### Validation Phase + +1. **Acceptance Testing**: Verify against defined criteria + +2. **Platform Testing**: Validate across target platforms + +3. **Performance Testing**: Ensure performance requirements met + +4. **Documentation**: Update relevant documentation + +## Remember + +**Your first estimate is wrong. Your second estimate is probably still +wrong. Focus on progress, not deadlines.** + +--- + +**See also**: + +- `.cursor/rules/development/planning_examples.mdc` for detailed planning examples + +- `.cursor/rules/development/complexity_assessment.mdc` for complexity evaluation + +**Status**: Active development guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Project managers + +## Model Implementation Checklist + +### Before Time Estimation + +- [ ] **Requirements Analysis**: Understand all requirements and acceptance criteria +- [ ] **Complexity Assessment**: Evaluate technical and business complexity +- [ ] **Platform Review**: Identify requirements across all target platforms +- [ ] **Stakeholder Input**: Gather input from all affected parties + +### During Time Estimation + +- [ ] **Phase Breakdown**: Divide work into logical, testable phases +- [ ] **Complexity Classification**: Assign complexity levels (Low/Medium/High/Critical) +- [ ] **Platform Considerations**: Account for platform-specific requirements +- [ ] **Testing Strategy**: Plan comprehensive testing approach + +### After Time Estimation + +- [ ] **Milestone Definition**: Define success criteria for each phase +- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms +- [ ] **Documentation**: Document estimation process and assumptions +- [ ] **Stakeholder Communication**: Share estimation approach and progress focus diff --git a/.cursor/rules/research_diagnostic.mdc b/.cursor/rules/development/research_diagnostic.mdc similarity index 72% rename from .cursor/rules/research_diagnostic.mdc rename to .cursor/rules/development/research_diagnostic.mdc index d82c9097..9d3c31aa 100644 --- a/.cursor/rules/research_diagnostic.mdc +++ b/.cursor/rules/development/research_diagnostic.mdc @@ -1,8 +1,12 @@ --- -description: Use this workflow when doing **pre-implementation research, defect investigations with uncertain repros, or clarifying system architecture and behaviors**. +description: Use this workflow when doing **pre-implementation research, defect + investigations with uncertain repros, or clarifying system architecture and + behaviors**. alwaysApply: false --- + ```json + { "coaching_level": "light", "socratic_max_questions": 2, @@ -10,6 +14,7 @@ alwaysApply: false "timebox_minutes": null, "format_enforcement": "strict" } + ``` # Research & Diagnostic Workflow (R&D) @@ -23,7 +28,9 @@ steps—**not** code changes. ## When to Use - Pre-implementation research for new features + - Defect investigations (repros uncertain, user-specific failures) + - Architecture/behavior clarifications (e.g., auth flows, merges, migrations) --- @@ -33,7 +40,9 @@ steps—**not** code changes. When investigating software issues, also apply: - **Code Path Tracing**: Required for technical investigations + - **Evidence Validation**: Ensure claims are code-backed + - **Solution Complexity Assessment**: Justify architectural changes --- @@ -60,48 +69,73 @@ When investigating software issues, also apply: Copy/paste and fill: ```md + # Investigation — ## Objective + ## System Map + - → → + - → → ## Findings (Evidence) -- — evidence: `src/path/file.ts:function` (lines X–Y); log snippet/trace id + +- — + + evidence: `src/path/file.ts:function` (lines X–Y); log snippet/trace id + - — evidence: `...` ## Hypotheses & Failure Modes + - H1: ; would fail when + - H2: ; watch for ## Corrections + - Updated: → ## Diagnostics (Next Checks) + - [ ] Repro on + - [ ] Inspect for + - [ ] Capture ## Risks & Scope + - Impacted: ; Data: ; Users: ## Decision / Next Steps + - Owner: ; By: (YYYY-MM-DD) + - Action: ; Exit criteria: ## References + - `src/...` + - ADR: `docs/adr/xxxx-yy-zz-something.md` + - Design: `docs/...` ## Competence Hooks + - Why this works: <≤3 bullets> + - Common pitfalls: <≤3 bullets> + - Next skill: <≤1 item> + - Teach-back: "" + ``` --- @@ -109,8 +143,13 @@ Copy/paste and fill: ## Evidence Quality Bar - **Cite the source** (file:func, line range if possible). + - **Prefer primary evidence** (code, logs) over inference. -- **Disambiguate platform** (Web/Capacitor/Electron) and **state** (migration, auth). + +- **Disambiguate platform** (Web/Capacitor/Electron) and **state** (migration, + + auth). + - **Note uncertainty** explicitly. --- @@ -119,10 +158,16 @@ Copy/paste and fill: Before proposing solutions, trace the actual execution path: -- [ ] **Entry Points**: Identify where the flow begins (user action, API call, etc.) +- [ ] **Entry Points**: + + Identify where the flow begins (user action, API call, etc.) + - [ ] **Component Flow**: Map which components/methods are involved + - [ ] **Data Path**: Track how data moves through the system + - [ ] **Exit Points**: Confirm where the flow ends and what results + - [ ] **Evidence Collection**: Gather specific code citations for each step --- @@ -130,7 +175,9 @@ Before proposing solutions, trace the actual execution path: ## Collaboration Hooks - **Syncs:** 10–15m with QA/Security/Platform owners for high-risk areas. + - **ADR:** Record major decisions; link here. + - **Review:** Share repro + diagnostics checklist in PR/issue. --- @@ -139,13 +186,20 @@ Before proposing solutions, trace the actual execution path: ### With software_development.mdc -- **Enhanced Evidence Validation**: Use code path tracing for technical investigations -- **Architecture Assessment**: Apply complexity justification to proposed solutions +- **Enhanced Evidence Validation**: + + Use code path tracing for technical investigations + +- **Architecture Assessment**: + + Apply complexity justification to proposed solutions + - **Impact Analysis**: Assess effects on existing systems before recommendations ### With base_context.mdc - **Competence Building**: Focus on technical investigation skills + - **Collaboration**: Structure outputs for team review and discussion --- @@ -153,11 +207,17 @@ Before proposing solutions, trace the actual execution path: ## Self-Check (model, before responding) - [ ] Output matches the **Output Contract** sections. + - [ ] Each claim has **evidence** or **uncertainty** is flagged. + - [ ] Hypotheses are testable; diagnostics are actionable. + - [ ] Competence + collaboration hooks present (≤120 words total). + - [ ] Respect toggles; keep it concise. + - [ ] **Code path traced** (for software investigations). + - [ ] **Evidence validated** against actual code execution. --- @@ -166,9 +226,37 @@ Before proposing solutions, trace the actual execution path: > Uncomment `globs` in the header if you want auto-attach behavior. -- `src/platforms/**`, `src/services/**` — attach during service/feature investigations +- `src/platforms/**`, `src/services/**` — + + attach during service/feature investigations + - `docs/adr/**` — attach when editing ADRs ## Referenced Files -- Consider including templates as context: `@adr_template.mdc`, `@investigation_report_example.mdc` +- Consider including templates as context: `@adr_template.mdc`, + + `@investigation_report_example.mdc` + +## Model Implementation Checklist + +### Before Investigation + +- [ ] **Problem Definition**: Clearly define the research question or issue +- [ ] **Scope Definition**: Determine investigation scope and boundaries +- [ ] **Methodology Planning**: Plan investigation approach and methods +- [ ] **Resource Assessment**: Identify required resources and tools + +### During Investigation + +- [ ] **Evidence Collection**: Gather relevant evidence and data systematically +- [ ] **Code Path Tracing**: Map execution flow for software investigations +- [ ] **Analysis**: Analyze evidence using appropriate methods +- [ ] **Documentation**: Document investigation process and findings + +### After Investigation + +- [ ] **Synthesis**: Synthesize findings into actionable insights +- [ ] **Report Creation**: Create comprehensive investigation report +- [ ] **Recommendations**: Provide clear, actionable recommendations +- [ ] **Team Communication**: Share findings and next steps with team diff --git a/.cursor/rules/software_development.mdc b/.cursor/rules/development/software_development.mdc similarity index 53% rename from .cursor/rules/software_development.mdc rename to .cursor/rules/development/software_development.mdc index 2f7c2c71..bbf3da4e 100644 --- a/.cursor/rules/software_development.mdc +++ b/.cursor/rules/development/software_development.mdc @@ -1,4 +1,9 @@ +--- + +alwaysApply: false +--- + # Software Development Ruleset **Author**: Matthew Raymer @@ -15,34 +20,52 @@ debugging, architecture decisions, and testing. ### 1. Evidence-First Development - **Code Citations Required**: Always cite specific file:line references when + making claims + - **Execution Path Tracing**: Trace actual code execution before proposing + architectural changes + - **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based" ### 2. Code Review Standards - **Trace Before Proposing**: Always trace execution paths before suggesting + changes + - **Evidence Over Inference**: Prefer code citations over logical deductions + - **Scope Validation**: Confirm the actual scope of problems before proposing + solutions ### 3. Problem-Solution Validation - **Problem Scope**: Does the solution address the actual problem? + - **Evidence Alignment**: Does the solution match the evidence? + - **Complexity Justification**: Is added complexity justified by real needs? + - **Alternative Analysis**: What simpler solutions were considered? ### 4. Dependency Management & Environment Validation -- **Pre-build Validation**: Always validate critical dependencies before executing +- **Pre-build Validation**: + + Always validate critical dependencies before executing build scripts + - **Environment Consistency**: Ensure team members have identical development + environments + - **Dependency Verification**: Check that required packages are installed and + accessible + - **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues ## Required Workflows @@ -50,18 +73,27 @@ debugging, architecture decisions, and testing. ### Before Proposing Changes - [ ] **Code Path Tracing**: Map execution flow from entry to exit + - [ ] **Evidence Collection**: Gather specific code citations and logs + - [ ] **Assumption Surfacing**: Identify what's proven vs. inferred + - [ ] **Scope Validation**: Confirm the actual extent of the problem + - [ ] **Dependency Validation**: Verify all required dependencies are available + and accessible ### During Solution Design - [ ] **Evidence Alignment**: Ensure solution addresses proven problems + - [ ] **Complexity Assessment**: Justify any added complexity + - [ ] **Alternative Evaluation**: Consider simpler approaches first + - [ ] **Impact Analysis**: Assess effects on existing systems + - [ ] **Environment Impact**: Assess how changes affect team member setups ## Software-Specific Competence Hooks @@ -69,78 +101,53 @@ debugging, architecture decisions, and testing. ### Evidence Validation - **"What code path proves this claim?"** + - **"How does data actually flow through the system?"** + - **"What am I assuming vs. what can I prove?"** ### Code Tracing - **"What's the execution path from user action to system response?"** + - **"Which components actually interact in this scenario?"** + - **"Where does the data originate and where does it end up?"** ### Architecture Decisions - **"What evidence shows this change is necessary?"** + - **"What simpler solution could achieve the same goal?"** + - **"How does this change affect the existing system architecture?"** ### Dependency & Environment Management - **"What dependencies does this feature require and are they properly - declared?"** -- **"How will this change affect team member development environments?"** -- **"What validation can we add to catch dependency issues early?"** - -## Dependency Management Best Practices - -### Pre-build Validation - -- **Check Critical Dependencies**: Validate essential tools before executing build - scripts -- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to - avoid PATH issues -- **Environment Consistency**: Ensure all team members have identical dependency - versions - -### Common Pitfalls - -- **Missing npm install**: Team members cloning without running `npm install` -- **PATH Issues**: Direct command execution vs. npm script execution differences -- **Version Mismatches**: Different Node.js/npm versions across team members - -### Validation Strategies -- **Dependency Check Scripts**: Implement pre-build validation for critical - dependencies -- **Environment Requirements**: Document and enforce minimum Node.js/npm versions -- **Onboarding Checklist**: Standardize team member setup procedures - -### Error Messages and Guidance - -- **Specific Error Context**: Provide clear guidance when dependency issues occur -- **Actionable Solutions**: Direct users to specific commands (`npm install`, - `npm run check:dependencies`) -- **Environment Diagnostics**: Implement comprehensive environment validation - tools + declared?"** -### Build Script Enhancements +- **"How will this change affect team member development environments?"** -- **Early Validation**: Check dependencies before starting build processes -- **Graceful Degradation**: Continue builds when possible but warn about issues -- **Helpful Tips**: Remind users about dependency management best practices +- **"What validation can we add to catch dependency issues early?"** ## Integration with Other Rulesets ### With base_context.mdc - Inherits generic competence principles + - Adds software-specific evidence requirements + - Maintains collaboration and learning focus ### With research_diagnostic.mdc - Enhances investigation with code path tracing + - Adds evidence validation to diagnostic workflow + - Strengthens problem identification accuracy ## Usage Guidelines @@ -148,78 +155,73 @@ debugging, architecture decisions, and testing. ### When to Use This Ruleset - Code reviews and architectural decisions + - Bug investigation and debugging + - Performance optimization + - Feature implementation planning + - Testing strategy development ### When to Combine with Others - **base_context + software_development**: General development tasks + - **research_diagnostic + software_development**: Technical investigations + - **All three**: Complex architectural decisions or major refactoring ## Self-Check (model, before responding) - [ ] Code path traced and documented + - [ ] Evidence cited with specific file:line references + - [ ] Assumptions clearly flagged as proven vs. inferred + - [ ] Solution complexity justified by evidence + - [ ] Simpler alternatives considered and documented -- [ ] Impact on existing systems assessed -- [ ] Dependencies validated and accessible -- [ ] Environment impact assessed for team members -- [ ] Pre-build validation implemented where appropriate -## Additional Core Principles +- [ ] Impact on existing systems assessed -### 4. Dependency Management & Environment Validation -- **Pre-build Validation**: Always validate critical dependencies before executing build scripts -- **Environment Consistency**: Ensure team members have identical development environments -- **Dependency Verification**: Check that required packages are installed and accessible -- **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues +- [ ] Dependencies validated and accessible -## Additional Required Workflows +- [ ] Environment impact assessed for team members -### Dependency Validation (Before Proposing Changes) -- [ ] **Dependency Validation**: Verify all required dependencies are available and accessible +- [ ] Pre-build validation implemented where appropriate -### Environment Impact Assessment (During Solution Design) -- [ ] **Environment Impact**: Assess how changes affect team member setups +--- -## Additional Competence Hooks +**See also**: `.cursor/rules/development/dependency_management.mdc` for + detailed dependency management practices. -### Dependency & Environment Management -- **"What dependencies does this feature require and are they properly declared?"** -- **"How will this change affect team member development environments?"** -- **"What validation can we add to catch dependency issues early?"** +**Status**: Active development guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: base_context.mdc, research_diagnostic.mdc +**Stakeholders**: Development team, Code review team -## Dependency Management Best Practices +## Model Implementation Checklist -### Pre-build Validation -- **Check Critical Dependencies**: Validate essential tools before executing build scripts -- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to avoid PATH issues -- **Environment Consistency**: Ensure all team members have identical dependency versions +### Before Development Work -### Common Pitfalls -- **Missing npm install**: Team members cloning without running `npm install` -- **PATH Issues**: Direct command execution vs. npm script execution differences -- **Version Mismatches**: Different Node.js/npm versions across team members +- [ ] **Code Path Tracing**: Map execution flow from entry to exit +- [ ] **Evidence Collection**: Gather specific code citations and logs +- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred +- [ ] **Scope Validation**: Confirm the actual extent of the problem -### Validation Strategies -- **Dependency Check Scripts**: Implement pre-build validation for critical dependencies -- **Environment Requirements**: Document and enforce minimum Node.js/npm versions -- **Onboarding Checklist**: Standardize team member setup procedures +### During Development -### Error Messages and Guidance -- **Specific Error Context**: Provide clear guidance when dependency issues occur -- **Actionable Solutions**: Direct users to specific commands (`npm install`, `npm run check:dependencies`) -- **Environment Diagnostics**: Implement comprehensive environment validation tools +- [ ] **Evidence Alignment**: Ensure solution addresses proven problems +- [ ] **Complexity Assessment**: Justify any added complexity +- [ ] **Alternative Evaluation**: Consider simpler approaches first +- [ ] **Impact Analysis**: Assess effects on existing systems -### Build Script Enhancements -- **Early Validation**: Check dependencies before starting build processes -- **Graceful Degradation**: Continue builds when possible but warn about issues -- **Helpful Tips**: Remind users about dependency management best practices +### After Development -- **Narrow Types Properly**: Use type guards to narrow `unknown` types safely -- **Document Type Decisions**: Explain complex type structures and their purpose +- [ ] **Code Path Validation**: Verify execution paths are correct +- [ ] **Evidence Documentation**: Document all code citations and evidence +- [ ] **Assumption Review**: Confirm all assumptions are documented +- [ ] **Environment Impact**: Assess how changes affect team member setups diff --git a/.cursor/rules/development/time.mdc b/.cursor/rules/development/time.mdc new file mode 100644 index 00000000..9aeb172b --- /dev/null +++ b/.cursor/rules/development/time.mdc @@ -0,0 +1,146 @@ +# Time Handling in Development Workflow + +**Author**: Matthew Raymer +**Date**: 2025-08-17 +**Status**: 🎯 **ACTIVE** - Production Ready + +## Overview + +This guide establishes **how time should be referenced and used** across the +development workflow. It is not tied to any one project, but applies to **all +feature development, issue investigations, ADRs, and documentation**. + +## General Principles + +- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over + + relative references like "last week." + +- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in + + docs, issues, ADRs, and commits. + +- **Time zones**: Default to **UTC** unless explicitly tied to user-facing + + behavior. + +- **Precision**: Only specify as much precision as needed (date vs. datetime vs. + + timestamp). + +- **Consistency**: Align time references across ADRs, commits, and investigation + + reports. + +## In Documentation & ADRs + +- Record decision dates using **absolute ISO dates**. + +- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` → + + `2025-08-17`). + +- Avoid ambiguous terms like *recently*, *last month*, or *soon*. + +- For time-based experiments (e.g., A/B tests), always include: + + - Start date + + - Expected duration + + - Review date checkpoint + +## In Code & Commits + +- Use **UTC timestamps** in logs, DB migrations, and serialized formats. + +- In commits, link changes to **date-bound ADRs or investigation docs**. + +- For migrations, include both **applied date** and **intended version window**. + +- Use constants for known fixed dates; avoid hardcoding arbitrary strings. + +## In Investigations & Research + +- Capture **when** an issue occurred (absolute time or version tag). + +- When describing failures: note whether they are **time-sensitive** (e.g., + + after + migrations, cache expirations). + +- Record diagnostic timelines in ISO format (not relative). + +- For performance regressions, annotate both **baseline timeframe** and + + **measurement timeframe**. + +## Collaboration Hooks + +- During reviews, verify **time references are clear, absolute, and + + standardized**. + +- In syncs, reframe relative terms ("this week") into shared absolute + + references. + +- Tag ADRs with both **date created** and **review by** checkpoints. + +## Self-Check Before Submitting + +- [ ] Did I check the time using the **developer's actual system time and + + timezone**? + +- [ ] Am I using absolute ISO dates? + +- [ ] Is UTC assumed unless specified otherwise? + +- [ ] Did I avoid ambiguous relative terms? + +- [ ] If duration matters, did I specify both start and end? + +- [ ] For future work, did I include a review/revisit date? + +--- + +**See also**: + +- `.cursor/rules/development/time_implementation.mdc` for + + detailed implementation instructions + +- `.cursor/rules/development/time_examples.mdc` for practical examples and patterns + +**Status**: Active time handling guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Documentation team + +**Maintainer**: Matthew Raymer +**Next Review**: 2025-09-17 + +## Model Implementation Checklist + +### Before Time-Related Work + +- [ ] **Time Context**: Understand what time information is needed +- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) +- [ ] **Platform Check**: Identify platform-specific time requirements +- [ ] **User Context**: Consider user's timezone and preferences + +### During Time Implementation + +- [ ] **UTC Usage**: Use UTC for all system and log timestamps +- [ ] **Format Consistency**: Apply consistent time formatting patterns +- [ ] **Timezone Handling**: Properly handle timezone conversions +- [ ] **User Display**: Format times appropriately for user display + +### After Time Implementation + +- [ ] **Validation**: Verify time formats are correct and consistent +- [ ] **Testing**: Test time handling across different scenarios +- [ ] **Documentation**: Update relevant documentation with time patterns +- [ ] **Review**: Confirm implementation follows time standards diff --git a/.cursor/rules/development/time_examples.mdc b/.cursor/rules/development/time_examples.mdc new file mode 100644 index 00000000..f8a3d563 --- /dev/null +++ b/.cursor/rules/development/time_examples.mdc @@ -0,0 +1,243 @@ +# Time Examples — Practical Patterns + +> **Agent role**: Reference this file for practical examples and + patterns when working with time handling in development. + +## Examples + +### Good + +- "Feature flag rollout started on `2025-08-01` and will be reviewed on + + `2025-08-21`." + +- "Migration applied on `2025-07-15T14:00Z`." + +- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` / + + `2025-08-17T14:00Z (UTC)`." + +### Bad + +- "Feature flag rolled out last week." + +- "Migration applied recently." + +- "Now is August, so we assume this was last month." + +### More Examples + +#### Issue Reports + +- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue + + persisted until `2025-08-17T15:45:00Z`." + +- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a + + while." + +#### Release Planning + +- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing + + window: `2025-08-20` to `2025-08-24`." + +- ❌ **Bad**: "Feature X will be released next week after testing." + +#### Performance Monitoring + +- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`. + + Regression detected on `2025-08-15T14:00:00Z`." + +- ❌ **Bad**: "Performance was good last week but got worse this week." + +## Technical Implementation Examples + +### Database Storage + +```sql + +-- ✅ Good: Store in UTC +created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, +updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP + +-- ❌ Bad: Store in local time +created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, +updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP + +``` + +### API Responses + +```json + +// ✅ Good: Include both UTC and local time +{ + "eventTime": "2025-08-17T14:00:00Z", + "localTime": "2025-08-17T10:00:00-04:00", + "timezone": "America/New_York" +} + +// ❌ Bad: Only local time +{ + "eventTime": "2025-08-17T10:00:00-04:00" +} + +``` + +### Logging + +```python + +# ✅ Good: Log in UTC with timezone info + +logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)") + +# ❌ Bad: Log in local time + +logger.info(f"User action at {datetime.now()}") + +``` + +## Timezone Handling Examples + +### Good Timezone Usage + +```typescript + +// ✅ Good: Store UTC, convert for display +const eventTime = new Date().toISOString(); // Store in UTC +const localTime = new Date().toLocaleString('en-US', { + timeZone: 'America/New_York' +}); // Convert for display + +// ✅ Good: Include timezone context +const timestamp = { + utc: "2025-08-17T14:00:00Z", + local: "2025-08-17T10:00:00-04:00", + timezone: "America/New_York" +}; + +``` + +### Bad Timezone Usage + +```typescript + +// ❌ Bad: Assume timezone +const now = new Date(); // Assumes system timezone + +// ❌ Bad: Mix formats +const timestamp = "2025-08-17 10:00 AM"; // Ambiguous format + +``` + +## Common Patterns + +### Date Range References + +```typescript + +// ✅ Good: Explicit date ranges +const dateRange = { + start: "2025-08-01T00:00:00Z", + end: "2025-08-31T23:59:59Z" +}; + +// ❌ Bad: Relative ranges +const dateRange = { + start: "beginning of month", + end: "end of month" +}; + +``` + +### Duration References + +```typescript + +// ✅ Good: Specific durations +const duration = { + value: 30, + unit: "days", + startDate: "2025-08-01T00:00:00Z" +}; + +// ❌ Bad: Vague durations +const duration = "about a month"; + +``` + +### Version References + +```typescript + +// ✅ Good: Version with date +const version = { + number: "1.2.3", + releaseDate: "2025-08-17T10:00:00Z", + buildDate: "2025-08-17T09:30:00Z" +}; + +// ❌ Bad: Version without context +const version = "latest"; + +``` + +## References + +- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601) + +- [IANA Timezone Database](https://www.iana.org/time-zones) + +- [ADR Template](./adr_template.md) + +- [Research & Diagnostic Workflow](./research_diagnostic.mdc) + +--- + +**Rule of Thumb**: Every time reference in development artifacts should be +**clear in 6 months without context**, and aligned to the **developer's actual +current time**. + +**Technical Rule of Thumb**: **Store in UTC, display in local time, always +include timezone context.** + +--- + +**See also**: + +- `.cursor/rules/development/time.mdc` for core principles + +- `.cursor/rules/development/time_implementation.mdc` for implementation instructions + +**Status**: Active examples and patterns +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: time.mdc, time_implementation.mdc +**Stakeholders**: Development team, Documentation team + +## Model Implementation Checklist + +### Before Time Implementation + +- [ ] **Time Context**: Understand what time information needs to be implemented +- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) +- [ ] **Platform Check**: Identify platform-specific time requirements +- [ ] **User Context**: Consider user's timezone and display preferences + +### During Time Implementation + +- [ ] **UTC Storage**: Use UTC for all system and log timestamps +- [ ] **Format Consistency**: Apply consistent time formatting patterns +- [ ] **Timezone Handling**: Properly handle timezone conversions +- [ ] **User Display**: Format times appropriately for user display + +### After Time Implementation + +- [ ] **Format Validation**: Verify time formats are correct and consistent +- [ ] **Cross-Platform Testing**: Test time handling across different platforms +- [ ] **Documentation**: Update relevant documentation with time patterns +- [ ] **User Experience**: Confirm time display is clear and user-friendly diff --git a/.cursor/rules/time.mdc b/.cursor/rules/development/time_implementation.mdc similarity index 54% rename from .cursor/rules/time.mdc rename to .cursor/rules/development/time_implementation.mdc index 61c962bb..f5c2da2a 100644 --- a/.cursor/rules/time.mdc +++ b/.cursor/rules/development/time_implementation.mdc @@ -1,91 +1,28 @@ ---- -alwaysApply: true ---- -# Time Handling in Development Workflow - -**Author**: Matthew Raymer -**Date**: 2025-08-17 -**Status**: 🎯 **ACTIVE** - Production Ready - -## Overview - -This guide establishes **how time should be referenced and used** across the -development workflow. It is not tied to any one project, but applies to **all -feature development, issue investigations, ADRs, and documentation**. - -## General Principles - -- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over - relative references like "last week." -- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in - docs, issues, ADRs, and commits. -- **Time zones**: Default to **UTC** unless explicitly tied to user-facing - behavior. -- **Precision**: Only specify as much precision as needed (date vs. datetime vs. - timestamp). -- **Consistency**: Align time references across ADRs, commits, and investigation - reports. - -## In Documentation & ADRs - -- Record decision dates using **absolute ISO dates**. -- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` → - `2025-08-17`). -- Avoid ambiguous terms like *recently*, *last month*, or *soon*. -- For time-based experiments (e.g., A/B tests), always include: - - - Start date - - Expected duration - - Review date checkpoint - -## In Code & Commits - -- Use **UTC timestamps** in logs, DB migrations, and serialized formats. -- In commits, link changes to **date-bound ADRs or investigation docs**. -- For migrations, include both **applied date** and **intended version window**. -- Use constants for known fixed dates; avoid hardcoding arbitrary strings. - -## In Investigations & Research +# Time Implementation — Technical Instructions -- Capture **when** an issue occurred (absolute time or version tag). -- When describing failures: note whether they are **time-sensitive** (e.g., after - migrations, cache expirations). -- Record diagnostic timelines in ISO format (not relative). -- For performance regressions, annotate both **baseline timeframe** and - **measurement timeframe**. - -## Collaboration Hooks - -- During reviews, verify **time references are clear, absolute, and - standardized**. -- In syncs, reframe relative terms ("this week") into shared absolute - references. -- Tag ADRs with both **date created** and **review by** checkpoints. - -## Self-Check Before Submitting - -- [ ] Did I check the time using the **developer's actual system time and - timezone**? -- [ ] Am I using absolute ISO dates? -- [ ] Is UTC assumed unless specified otherwise? -- [ ] Did I avoid ambiguous relative terms? -- [ ] If duration matters, did I specify both start and end? -- [ ] For future work, did I include a review/revisit date? +> **Agent role**: Reference this file for detailed implementation instructions + when working with time handling in development. ## Real-Time Context in Developer Interactions - The model must always resolve **"current time"** using the **developer's + actual system time and timezone**. + - When generating timestamps (e.g., in investigation logs, ADRs, or examples), + the model should: - Use the **developer's current local time** by default. + - Indicate the timezone explicitly (e.g., `2025-08-17T10:32-05:00`). + - Optionally provide UTC alongside if context requires cross-team clarity. - When interpreting relative terms like *now*, *today*, *last week*: - Resolve them against the **developer's current time**. + - Convert them into **absolute ISO-8601 values** in the output. ## LLM Time Checking Instructions @@ -98,15 +35,21 @@ than assuming or inventing times. #### 1. **Query System Time (Required)** - **Always start** by querying the current system time using available tools + - **Never assume** what the current time is + - **Never use** placeholder values like "current time" or "now" #### 2. **Available Time Query Methods** - **System Clock**: Use `date` command or equivalent system time function + - **Programming Language**: Use language-specific time functions (e.g., + `Date.now()`, `datetime.now()`) + - **Environment Variables**: Check for time-related environment variables + - **API Calls**: Use time service APIs if available #### 3. **Required Time Information** @@ -114,53 +57,75 @@ than assuming or inventing times. When querying time, always obtain: - **Current Date**: YYYY-MM-DD format + - **Current Time**: HH:MM:SS format (24-hour) + - **Timezone**: Current system timezone or UTC offset + - **UTC Equivalent**: Convert local time to UTC for cross-team clarity #### 4. **Time Query Examples** ```bash + # Example: Query system time + $ date + # Expected output: Mon Aug 17 10:32:45 EDT 2025 # Example: Query UTC time + $ date -u + # Expected output: Mon Aug 17 14:32:45 UTC 2025 + ``` ```python + # Example: Python time query + import datetime current_time = datetime.datetime.now() utc_time = datetime.datetime.utcnow() print(f"Local: {current_time}") print(f"UTC: {utc_time}") + ``` ```javascript + // Example: JavaScript time query const now = new Date(); const utc = new Date().toISOString(); console.log(`Local: ${now}`); console.log(`UTC: ${utc}`); + ``` #### 5. **LLM Time Checking Workflow** 1. **Query**: Actively query system for current time + 2. **Validate**: Confirm time data is reasonable and current + 3. **Format**: Convert to ISO 8601 format + 4. **Context**: Provide both local and UTC times when helpful + 5. **Document**: Show the source of time information #### 6. **Error Handling for Time Queries** - **If time query fails**: Ask user for current time or use "unknown time" + with explanation + - **If timezone unclear**: Default to UTC and ask for clarification + - **If time seems wrong**: Verify with user before proceeding + - **Always log**: Record when and how time was obtained #### 7. **Time Query Verification** @@ -168,64 +133,37 @@ console.log(`UTC: ${utc}`); Before using queried time, verify: - [ ] Time is recent (within last few minutes) + - [ ] Timezone information is available + - [ ] UTC conversion is accurate + - [ ] Format follows ISO 8601 standard ## Model Behavior Rules - **Never invent a "fake now"**: All "current time" references must come from + the real system clock available at runtime. + - **Check developer time zone**: If ambiguous, ask for clarification (e.g., + "Should I use UTC or your local timezone?"). + - **Format for clarity**: - Local time: `YYYY-MM-DDTHH:mm±hh:mm` - - UTC equivalent (if needed): `YYYY-MM-DDTHH:mmZ` - -## Examples - -### Good - -- "Feature flag rollout started on `2025-08-01` and will be reviewed on - `2025-08-21`." -- "Migration applied on `2025-07-15T14:00Z`." -- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` / - `2025-08-17T14:00Z (UTC)`." -### Bad - -- "Feature flag rolled out last week." -- "Migration applied recently." -- "Now is August, so we assume this was last month." - -### More Examples - -#### Issue Reports - -- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue - persisted until `2025-08-17T15:45:00Z`." -- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a - while." - -#### Release Planning - -- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing - window: `2025-08-20` to `2025-08-24`." -- ❌ **Bad**: "Feature X will be released next week after testing." - -#### Performance Monitoring - -- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`. - Regression detected on `2025-08-15T14:00:00Z`." -- ❌ **Bad**: "Performance was good last week but got worse this week." + - UTC equivalent (if needed): `YYYY-MM-DDTHH:mmZ` ## Technical Implementation Notes ### UTC Storage Principle - **Store all timestamps in UTC** in databases, logs, and serialized formats + - **Convert to local time only for user display** + - **Use ISO 8601 format** for all storage: `YYYY-MM-DDTHH:mm:ss.sssZ` ### Common Implementation Patterns @@ -233,18 +171,17 @@ Before using queried time, verify: #### Database Storage ```sql + -- ✅ Good: Store in UTC created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP --- ❌ Bad: Store in local time -created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ``` #### API Responses ```json + // ✅ Good: Include both UTC and local time { "eventTime": "2025-08-17T14:00:00Z", @@ -252,20 +189,16 @@ updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP "timezone": "America/New_York" } -// ❌ Bad: Only local time -{ - "eventTime": "2025-08-17T10:00:00-04:00" -} ``` #### Logging ```python + # ✅ Good: Log in UTC with timezone info + logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)") -# ❌ Bad: Log in local time -logger.info(f"User action at {datetime.now()}") ``` ### Timezone Handling Best Practices @@ -273,19 +206,25 @@ logger.info(f"User action at {datetime.now()}") #### 1. Always Store Timezone Information - Include IANA timezone identifier (e.g., `America/New_York`) + - Store UTC offset at time of creation + - Handle daylight saving time transitions automatically #### 2. User Display Considerations - Convert UTC to user's preferred timezone + - Show timezone abbreviation when helpful + - Use relative time for recent events ("2 hours ago") #### 3. Edge Case Handling - **Daylight Saving Time**: Use timezone-aware libraries + - **Leap Seconds**: Handle gracefully (rare but important) + - **Invalid Times**: Validate before processing ### Common Mistakes to Avoid @@ -293,37 +232,54 @@ logger.info(f"User action at {datetime.now()}") #### 1. Timezone Confusion - ❌ **Don't**: Assume server timezone is user timezone + - ✅ **Do**: Always convert UTC to user's local time for display #### 2. Format Inconsistency - ❌ **Don't**: Mix different time formats in the same system + - ✅ **Do**: Standardize on ISO 8601 for all storage #### 3. Relative Time References - ❌ **Don't**: Use relative terms in persistent storage + - ✅ **Do**: Convert relative terms to absolute timestamps immediately -## References +--- -- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601) -- [IANA Timezone Database](https://www.iana.org/time-zones) -- [ADR Template](./adr_template.md) -- [Research & Diagnostic Workflow](./research_diagnostic.mdc) +**See also**: ---- +- `.cursor/rules/development/time.mdc` for core principles -**Rule of Thumb**: Every time reference in development artifacts should be -**clear in 6 months without context**, and aligned to the **developer's actual -current time**. +- `.cursor/rules/development/time_examples.mdc` for practical examples -**Technical Rule of Thumb**: **Store in UTC, display in local time, always -include timezone context.** +**Status**: Active implementation guidelines +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: time.mdc +**Stakeholders**: Development team, DevOps team ---- +## Model Implementation Checklist + +### Before Time Implementation + +- [ ] **Time Context**: Understand what time information needs to be implemented +- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601) +- [ ] **Platform Check**: Identify platform-specific time requirements +- [ ] **User Context**: Consider user's timezone and display preferences + +### During Time Implementation + +- [ ] **UTC Storage**: Use UTC for all system and log timestamps +- [ ] **Format Consistency**: Apply consistent time formatting patterns +- [ ] **Timezone Handling**: Properly handle timezone conversions +- [ ] **User Display**: Format times appropriately for user display + +### After Time Implementation -**Status**: Active -**Version**: 1.0 -**Maintainer**: Matthew Raymer -**Next Review**: 2025-09-17 +- [ ] **Format Validation**: Verify time formats are correct and consistent +- [ ] **Cross-Platform Testing**: Test time handling across different platforms +- [ ] **Documentation**: Update relevant documentation with time patterns +- [ ] **User Experience**: Confirm time display is clear and user-friendly diff --git a/.cursor/rules/development/type_safety_guide.mdc b/.cursor/rules/development/type_safety_guide.mdc index 9c23938a..4fa17ee8 100644 --- a/.cursor/rules/development/type_safety_guide.mdc +++ b/.cursor/rules/development/type_safety_guide.mdc @@ -2,7 +2,9 @@ description: when dealing with types and Typesript alwaysApply: false --- + ```json + { "coaching_level": "light", "socratic_max_questions": 7, @@ -10,6 +12,7 @@ alwaysApply: false "timebox_minutes": null, "format_enforcement": "strict" } + ``` # TypeScript Type Safety Guidelines @@ -25,18 +28,25 @@ Practical rules to keep TypeScript strict and predictable. Minimize exceptions. ## Core Rules 1. **No `any`** + - Use explicit types. If unknown, use `unknown` and **narrow** via guards. 2. **Error handling uses guards** + - Reuse guards from `src/interfaces/**` (e.g., `isDatabaseError`, + `isApiError`). + - Catch with `unknown`; never cast to `any`. 3. **Dynamic property access is type‑safe** + - Use `keyof` + `in` checks: ```ts + obj[k as keyof typeof obj] + ``` - Avoid `(obj as any)[k]`. @@ -46,24 +56,45 @@ Practical rules to keep TypeScript strict and predictable. Minimize exceptions. ### Core Type Safety Rules - **No `any` Types**: Use explicit types or `unknown` with proper type guards -- **Error Handling Uses Guards**: Implement and reuse type guards from `src/interfaces/**` -- **Dynamic Property Access**: Use `keyof` + `in` checks for type-safe property access + +- **Error Handling Uses Guards**: + + Implement and reuse type guards from `src/interfaces/**` + +- **Dynamic Property Access**: + + Use `keyof` + `in` checks for type-safe property access ### Type Guard Patterns + - **API Errors**: Use `isApiError(error)` guards for API error handling -- **Database Errors**: Use `isDatabaseError(error)` guards for database operations -- **Axios Errors**: Implement `isAxiosError(error)` guards for HTTP error handling + +- **Database Errors**: + + Use `isDatabaseError(error)` guards for database operations + +- **Axios Errors**: + + Implement `isAxiosError(error)` guards for HTTP error handling ### Implementation Guidelines -- **Avoid Type Assertions**: Replace `as any` with proper type guards and interfaces + +- **Avoid Type Assertions**: + + Replace `as any` with proper type guards and interfaces + - **Narrow Types Properly**: Use type guards to narrow `unknown` types safely + - **Document Type Decisions**: Explain complex type structures and their purpose ## Minimal Special Cases (document in PR when used) - **Vue refs / instances**: Use `ComponentPublicInstance` or specific + component types for dynamic refs. + - **3rd‑party libs without types**: Narrow immediately to a **known + interface**; do not leave `any` hanging. ## Patterns (short) @@ -71,31 +102,38 @@ Practical rules to keep TypeScript strict and predictable. Minimize exceptions. ### Database errors ```ts + try { await this.$addContact(contact); } catch (e: unknown) { if (isDatabaseError(e) && e.message.includes("Key already exists")) { /* handle duplicate */ } } + ``` ### API errors ```ts + try { await apiCall(); } catch (e: unknown) { if (isApiError(e)) { const msg = e.response?.data?.error?.message; } } + ``` ### Dynamic keys ```ts + const keys = Object.keys(newSettings).filter( - k => k in newSettings && newSettings[k as keyof typeof newSettings] !== undefined +k => k in newSettings && newSettings[k as keyof typeof newSettings] !== + undefined ); + ``` ## Checklists @@ -103,28 +141,38 @@ const keys = Object.keys(newSettings).filter( **Before commit** - [ ] No `any` (except documented, justified cases) + - [ ] Errors handled via guards + - [ ] Dynamic access uses `keyof`/`in` + - [ ] Imports point to correct interfaces/types **Code review** - [ ] Hunt hidden `as any` + - [ ] Guard‑based error paths verified + - [ ] Dynamic ops are type‑safe + - [ ] Prefer existing types over re‑inventing ## Tools - `npm run lint-fix` — lint & auto‑fix + - `npm run type-check` — strict type compilation (CI + pre‑release) + - IDE: enable strict TS, ESLint/TS ESLint, Volar (Vue 3) ## References -- TS Handbook — https://www.typescriptlang.org/docs/ -- TS‑ESLint — https://typescript-eslint.io/rules/ -- Vue 3 + TS — https://vuejs.org/guide/typescript/ +- TS Handbook — + +- TS‑ESLint — + +- Vue 3 + TS — --- @@ -134,6 +182,31 @@ const keys = Object.keys(newSettings).filter( **Dependencies**: TypeScript, ESLint, Vue 3 **Stakeholders**: Development team -- TS Handbook — https://www.typescriptlang.org/docs/ -- TS‑ESLint — https://typescript-eslint.io/rules/ -- Vue 3 + TS — https://vuejs.org/guide/typescript/ +- TS Handbook — + +- TS‑ESLint — + +- Vue 3 + TS — + +## Model Implementation Checklist + +### Before Type Implementation + +- [ ] **Type Analysis**: Understand current type definitions and usage +- [ ] **Interface Review**: Review existing interfaces and types +- [ ] **Error Handling**: Plan error handling with type guards +- [ ] **Dynamic Access**: Identify dynamic access patterns that need type safety + +### During Type Implementation + +- [ ] **Type Safety**: Ensure types provide meaningful safety guarantees +- [ ] **Error Guards**: Implement proper error handling with type guards +- [ ] **Dynamic Operations**: Use `keyof`/`in` for dynamic access +- [ ] **Import Validation**: Verify imports point to correct interfaces/types + +### After Type Implementation + +- [ ] **Linting Check**: Run `npm run lint-fix` to verify code quality +- [ ] **Type Check**: Run `npm run type-check` for strict type compilation +- [ ] **Code Review**: Hunt for hidden `as any` and type safety issues +- [ ] **Documentation**: Update type documentation and examples diff --git a/.cursor/rules/docs/documentation.mdc b/.cursor/rules/docs/documentation.mdc index 1902ca73..e6e57bac 100644 --- a/.cursor/rules/docs/documentation.mdc +++ b/.cursor/rules/docs/documentation.mdc @@ -1,14 +1,37 @@ --- -alwaysApply: true +alwaysApply: false --- # Directive for Documentation Generation 1. Produce a **small, focused set of documents** rather than an overwhelming volume. 2. Ensure the content is **maintainable and worth preserving**, so that humans -are motivated to keep it up to date. + are motivated to keep it up to date. 3. Prioritize **educational value**: the documents must clearly explain the -workings of the system. -4. Avoid **shallow, generic, or filler explanations** often found in -AI-generated documentation. + workings of the system. +4. Avoid **shallow, generic, or filler explanations** often found in AI-generated + documentation. 5. Aim for **clarity, depth, and usefulness**, so readers gain genuine understanding. 6. Always check the local system date to determine current date. + +## Model Implementation Checklist + +### Before Documentation Creation + +- [ ] **Scope Definition**: Define what needs to be documented +- [ ] **Audience Analysis**: Identify target readers and their needs +- [ ] **Content Planning**: Plan focused, educational content structure +- [ ] **Maintenance Planning**: Ensure content will be worth preserving + +### During Documentation Creation + +- [ ] **Educational Focus**: Clearly explain how the system works +- [ ] **Depth and Clarity**: Provide genuine understanding, not surface explanations +- [ ] **Focused Content**: Keep documents small and focused on specific topics +- [ ] **Current Date**: Check local system date for time-sensitive content + +### After Documentation Creation + +- [ ] **Quality Review**: Ensure content is clear, deep, and useful +- [ ] **Maintainability Check**: Verify content motivates humans to keep it updated +- [ ] **Audience Validation**: Confirm content meets target reader needs +- [ ] **Integration**: Integrate with existing documentation structure diff --git a/.cursor/rules/docs/markdown-automation.mdc b/.cursor/rules/docs/markdown-automation.mdc deleted file mode 100644 index b2da4927..00000000 --- a/.cursor/rules/docs/markdown-automation.mdc +++ /dev/null @@ -1,79 +0,0 @@ ---- -alwaysApply: true ---- - -# Markdown Automation System - -**Author**: Matthew Raymer -**Date**: 2025-08-20 -**Status**: 🎯 **ACTIVE** - Markdown formatting automation - -## Overview - -The Markdown Automation System ensures your markdown formatting standards are -followed **during content generation** by AI agents, not just applied after the -fact. - -## AI-First Approach - -### **Primary Method**: AI Agent Compliance - -- **AI agents follow markdown rules** while generating content -- **No post-generation fixes needed** - content is compliant from creation -- **Consistent formatting** across all generated documentation - -### **Secondary Method**: Automated Validation - -- **Pre-commit hooks** catch any remaining issues -- **GitHub Actions** validate formatting before merge -- **Manual tools** for bulk fixes when needed - -## How It Works - -### 1. **AI Agent Compliance** (Primary) - -- **When**: Every time AI generates markdown content -- **What**: AI follows markdown rules during generation -- **Result**: Content is properly formatted from creation - -### 2. **Pre-commit Hooks** (Backup) - -- **When**: Every time you commit -- **What**: Catches any remaining formatting issues -- **Result**: Clean, properly formatted markdown files - -### 3. **GitHub Actions** (Pre-merge) - -- **When**: Every pull request -- **What**: Validates markdown formatting across all files -- **Result**: Blocks merge if formatting issues exist - -## AI Agent Rules Integration - -The AI agent follows markdown rules defined in `.cursor/rules/docs/markdown.mdc`: - -- **alwaysApply: true** - Rules are enforced during generation -- **Line Length**: AI never generates lines > 80 characters -- **Blank Lines**: AI adds proper spacing around all elements -- **Structure**: AI uses established templates and patterns - -## Available Commands - -### NPM Scripts - -- **`npm run markdown:setup`** - Install the automation system -- **`npm run markdown:fix`** - Fix formatting in all markdown files -- **`npm run markdown:check`** - Validate formatting without fixing - -## Benefits - -- **No more manual fixes** - AI generates compliant content from start -- **Consistent style** - All files follow same standards -- **Faster development** - No need to fix formatting manually - ---- - -**Status**: Active automation system -**Priority**: High -**Maintainer**: Development team -**Next Review**: 2025-09-20 diff --git a/.cursor/rules/docs/markdown.mdc b/.cursor/rules/docs/markdown.mdc deleted file mode 100644 index fddda015..00000000 --- a/.cursor/rules/docs/markdown.mdc +++ /dev/null @@ -1,366 +0,0 @@ ---- -globs: ["*.md", "*.mdc"] -alwaysApply: false ---- -# Cursor Markdown Ruleset for TimeSafari Documentation - -## Overview - -This ruleset enforces consistent markdown formatting standards across all project -documentation, ensuring readability, maintainability, and compliance with -markdownlint best practices. - -**⚠️ CRITICAL FOR AI AGENTS**: These rules must be followed DURING content -generation, not applied after the fact. Always generate markdown that complies -with these standards from the start. - -## AI Generation Guidelines - -### **MANDATORY**: Follow These Rules While Writing - -When generating markdown content, you MUST: - -1. **Line Length**: Never exceed 80 characters per line -2. **Blank Lines**: Always add blank lines around headings, lists, and code - blocks -3. **Structure**: Use proper heading hierarchy and document templates -4. **Formatting**: Apply consistent formatting patterns immediately - -### **DO NOT**: Generate content that violates these rules - -- ❌ Generate long lines that need breaking -- ❌ Create content without proper blank line spacing -- ❌ Use inconsistent formatting patterns -- ❌ Assume post-processing will fix violations - -### **DO**: Generate compliant content from the start - -- ✅ Write within 80-character limits -- ✅ Add blank lines around all structural elements -- ✅ Use established templates and patterns -- ✅ Apply formatting standards immediately - -## General Formatting Standards - -### Line Length - -- **Maximum line length**: 80 characters -- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line length - enforcement -- **Rationale**: Ensures readability across different screen sizes and terminal - widths - -### Blank Lines - -- **Headings**: Must be surrounded by blank lines above and below -- **Lists**: Must be surrounded by blank lines above and below -- **Code blocks**: Must be surrounded by blank lines above and below -- **Maximum consecutive blank lines**: 1 (no multiple blank lines) -- **File start**: No blank lines at the beginning of the file -- **File end**: Single newline character at the end - -### Whitespace - -- **No trailing spaces**: Remove all trailing whitespace from lines -- **No tabs**: Use spaces for indentation -- **Consistent indentation**: 2 spaces for list items and nested content - -## Heading Standards - -### Format - -- **Style**: ATX-style headings (`#`, `##`, `###`, etc.) -- **Case**: Title case for general headings -- **Code references**: Use backticks for file names and technical terms - - ✅ `### Current package.json Scripts` - - ❌ `### Current Package.json Scripts` - -### Hierarchy - -- **H1 (#)**: Document title only -- **H2 (##)**: Major sections -- **H3 (###)**: Subsections -- **H4 (####)**: Sub-subsections -- **H5+**: Avoid deeper nesting - -## List Standards - -### Unordered Lists - -- **Marker**: Use `-` (hyphen) consistently -- **Indentation**: 2 spaces for nested items -- **Blank lines**: Surround lists with blank lines - -### Ordered Lists - -- **Format**: `1.`, `2.`, `3.` (sequential numbering) -- **Indentation**: 2 spaces for nested items -- **Blank lines**: Surround lists with blank lines - -### Task Lists - -- **Format**: `- [ ]` for incomplete, `- [x]` for complete -- **Use case**: Project planning, checklists, implementation tracking - -## Code Block Standards - -### Fenced Code Blocks - -- **Syntax**: Triple backticks with language specification -- **Languages**: `json`, `bash`, `typescript`, `javascript`, `yaml`, `markdown` -- **Blank lines**: Must be surrounded by blank lines above and below -- **Line length**: No enforcement within code blocks - -### Inline Code - -- **Format**: Single backticks for inline code references -- **Use case**: File names, commands, variables, properties - -## Special Content Standards - -### JSON Examples - -```json -{ - "property": "value", - "nested": { - "property": "value" - } -} -``` - -### Shell Commands - -```bash -# Command with comment -npm run build:web - -# Multi-line command -VITE_GIT_HASH=`git log -1 --pretty=format:%h` \ - vite build --config vite.config.web.mts -``` - -### TypeScript Examples - -```typescript -// Function with JSDoc -/** - * Get environment configuration - * @param env - Environment name - * @returns Environment config object - */ -const getEnvironmentConfig = (env: string) => { - switch (env) { - case 'prod': - return { /* production settings */ }; - default: - return { /* development settings */ }; - } -}; -``` - -## File Structure Standards - -### Document Header - -```markdown -# Document Title - -**Author**: Matthew Raymer -**Date**: YYYY-MM-DD -**Status**: 🎯 **STATUS** - Brief description - -## Overview - -Brief description of the document's purpose and scope. -``` - -### Section Organization - -1. **Overview/Introduction** -2. **Current State Analysis** -3. **Implementation Plan** -4. **Technical Details** -5. **Testing & Validation** -6. **Next Steps** - -## Markdownlint Configuration - -### Required Rules - -```json -{ - "MD013": { "code_blocks": false }, - "MD012": true, - "MD022": true, - "MD031": true, - "MD032": true, - "MD047": true, - "MD009": true -} -``` - -### Rule Explanations - -- **MD013**: Line length (disabled for code blocks) -- **MD012**: No multiple consecutive blank lines -- **MD022**: Headings should be surrounded by blank lines -- **MD031**: Fenced code blocks should be surrounded by blank lines -- **MD032**: Lists should be surrounded by blank lines -- **MD047**: Files should end with a single newline -- **MD009**: No trailing spaces - -## Validation Commands - -### Check Single File - -```bash -npx markdownlint docs/filename.md -``` - -### Check All Documentation - -```bash -npx markdownlint docs/ -``` - -### Auto-fix Common Issues - -```bash -# Remove trailing spaces -sed -i 's/[[:space:]]*$//' docs/filename.md - -# Remove multiple blank lines -sed -i '/^$/N;/^\n$/D' docs/filename.md - -# Add newline at end if missing -echo "" >> docs/filename.md -``` - -## Common Patterns - -### Implementation Plans - -```markdown -## Implementation Plan - -### Phase 1: Foundation (Day 1) - -#### 1.1 Component Setup - -- [ ] Create new component file -- [ ] Add basic structure -- [ ] Implement core functionality - -#### 1.2 Configuration - -- [ ] Update configuration files -- [ ] Add environment variables -- [ ] Test configuration loading -``` - -### Status Tracking - -```markdown -**Status**: ✅ **COMPLETE** - All phases finished -**Progress**: 75% (15/20 components) -**Next**: Ready for testing phase -``` - -### Performance Metrics - -```markdown -#### 📊 Performance Metrics -- **Build Time**: 2.3 seconds (50% faster than baseline) -- **Bundle Size**: 1.2MB (30% reduction) -- **Success Rate**: 100% (no failures in 50 builds) -``` - -## Enforcement - -### Pre-commit Hooks - -- Run markdownlint on all changed markdown files -- Block commits with linting violations -- Auto-fix common issues when possible - -### CI/CD Integration - -- Include markdownlint in build pipeline -- Generate reports for documentation quality -- Fail builds with critical violations - -### Team Guidelines - -- All documentation PRs must pass markdownlint -- Use provided templates for new documents -- Follow established patterns for consistency - -## Templates - -### New Document Template - -```markdown -# Document Title - -**Author**: Matthew Raymer -**Date**: YYYY-MM-DD -**Status**: 🎯 **PLANNING** - Ready for Implementation - -## Overview - -Brief description of the document's purpose and scope. - -## Current State - -Description of current situation or problem. - -## Implementation Plan - -### Phase 1: Foundation - -- [ ] Task 1 -- [ ] Task 2 - -## Next Steps - -1. **Review and approve plan** -2. **Begin implementation** -3. **Test and validate** - ---- - -**Status**: Ready for implementation -**Priority**: Medium -**Estimated Effort**: X days -**Dependencies**: None -**Stakeholders**: Development team -``` - ---- - -**Last Updated**: 2025-07-09 -**Version**: 1.0 -**Maintainer**: Matthew Raymer - - -### Heading Uniqueness - -- **Rule**: No duplicate heading content at the same level -- **Scope**: Within a single document -- **Rationale**: Maintains clear document structure and navigation -- **Example**: - - ```markdown - ## Features ✅ - ### Authentication - ### Authorization - - ## Features ❌ (Duplicate heading) - ### Security - ### Performance - ``` - ## Features ❌ (Duplicate heading) - ### Security - ### Performance - ``` \ No newline at end of file diff --git a/.cursor/rules/docs/markdown_core.mdc b/.cursor/rules/docs/markdown_core.mdc new file mode 100644 index 00000000..d6adf97b --- /dev/null +++ b/.cursor/rules/docs/markdown_core.mdc @@ -0,0 +1,175 @@ +# Markdown Core Standards & Automation + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Core markdown standards and automation + +## Overview + +This file combines core markdown formatting standards with automation +guidelines. AI agents must follow these rules DURING content generation, +not apply them after the fact. + +## AI Generation Guidelines + +### **MANDATORY**: Follow These Rules While Writing + +When generating markdown content, you MUST: + +1. **Line Length**: Never exceed 80 characters per line +2. **Blank Lines**: Always add blank lines around headings, lists, and + code blocks +3. **Structure**: Use proper heading hierarchy and document templates +4. **Formatting**: Apply consistent formatting patterns immediately + +### **DO NOT**: Generate content that violates these rules + +- ❌ Generate long lines that need breaking +- ❌ Create content without proper blank line spacing +- ❌ Use inconsistent formatting patterns +- ❌ Assume post-processing will fix violations + +### **DO**: Generate compliant content from the start + +- ✅ Write within 80-character limits +- ✅ Add blank lines around all structural elements +- ✅ Use established templates and patterns +- ✅ Apply formatting standards immediately + +## Core Formatting Standards + +### Line Length + +- **Maximum line length**: 80 characters +- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line + length enforcement +- **Rationale**: Ensures readability across different screen sizes and + terminal widths + +### Blank Lines + +- **Headings**: Must be surrounded by blank lines above and below +- **Lists**: Must be surrounded by blank lines above and below +- **Code blocks**: Must be surrounded by blank lines above and below +- **Maximum consecutive blank lines**: 1 (no multiple blank lines) +- **File start**: No blank lines at the beginning of the file +- **File end**: Single newline character at the end + +### Whitespace + +- **No trailing spaces**: Remove all trailing whitespace from lines +- **No tabs**: Use spaces for indentation +- **Consistent indentation**: 2 spaces for list items and nested content + +## Heading Standards + +### Format + +- **Style**: ATX-style headings (`#`, `##`, `###`, etc.) +- **Case**: Title case for general headings +- **Code references**: Use backticks for file names and technical terms + - ✅ `### Current package.json Scripts` + - ❌ `### Current Package.json Scripts` + +### Hierarchy + +- **H1 (#)**: Document title only +- **H2 (##)**: Major sections +- **H3 (###)**: Subsections +- **H4 (####)**: Sub-subsections +- **H5+**: Avoid deeper nesting + +## List Standards + +### Unordered Lists + +- **Marker**: Use `-` (hyphen) consistently +- **Indentation**: 2 spaces for nested items +- **Blank lines**: Surround lists with blank lines + +### Ordered Lists + +- **Format**: `1.`, `2.`, `3.` (sequential numbering) +- **Indentation**: 2 spaces for nested items +- **Blank lines**: Surround lists with blank lines + +### Task Lists + +- **Format**: `- [ ]` for incomplete, `- [x]` for complete +- **Indentation**: 2 spaces for nested items +- **Blank lines**: Surround lists with blank lines + +## Code Block Standards + +### Inline Code + +- **Format**: Single backticks for inline code +- **Use cases**: File names, commands, variables, technical terms +- **Examples**: `package.json`, `npm run build`, `VITE_PLATFORM` + +### Code Blocks + +- **Format**: Triple backticks with language specification +- **Language**: Always specify the language for syntax highlighting +- **Blank lines**: Surround with blank lines above and below + +## Automation System + +### Available Commands + +- **`npm run markdown:fix`** - Fix formatting in all markdown files + using markdownlint-cli2 --fix +- **`npm run markdown:check`** - Validate formatting without fixing + using markdownlint-cli2 + +### How It Works + +1. **AI Agent Compliance** (Primary): AI follows markdown rules during + generation +2. **Pre-commit Hooks** (Backup): Catches any remaining formatting + issues +3. **GitHub Actions** (Pre-merge): Validates formatting before merge + +### Benefits + +- **No more manual fixes** - AI generates compliant content from start +- **Consistent style** - All files follow same standards +- **Faster development** - No need to fix formatting manually + +## Model Implementation Checklist + +### Before Generating Markdown Content + +- [ ] **Line Length**: Ensure no line exceeds 80 characters +- [ ] **Blank Lines**: Add blank lines around headings, lists, and code blocks +- [ ] **Whitespace**: Remove all trailing spaces, use 2-space indentation +- [ ] **Headings**: Use ATX-style with proper hierarchy (H1 for title only) +- [ ] **Lists**: Use consistent markers (- for unordered, 1. for ordered) +- [ ] **Code**: Specify language for fenced blocks, use backticks for inline + +### After Generating Markdown Content + +- [ ] **Validation**: Run `npm run markdown:check` to verify compliance +- [ ] **Auto-fix**: Use `npm run markdown:fix` if any issues found +- [ ] **Review**: Confirm content follows established templates and patterns +- [ ] **Cross-reference**: Link to related documentation and templates + +### Quality Assurance + +- [ ] **Readability**: Content is clear and follows project conventions +- [ ] **Consistency**: Formatting matches existing documentation style +- [ ] **Completeness**: All required sections and information included +- [ ] **Accuracy**: Technical details are correct and up-to-date + +--- + +**See also**: + +- `.cursor/rules/docs/markdown_templates.mdc` for document templates +- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows + +**Status**: Active core standards and automation +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Documentation team, Development team diff --git a/.cursor/rules/docs/markdown_templates.mdc b/.cursor/rules/docs/markdown_templates.mdc new file mode 100644 index 00000000..46252bac --- /dev/null +++ b/.cursor/rules/docs/markdown_templates.mdc @@ -0,0 +1,219 @@ +# Markdown Templates & Examples + +> **Agent role**: Reference this file for document templates, structure, +> and examples when creating new documentation. + +## Document Templates + +### Standard Document Template + +```markdown +# Document Title + +**Author**: Matthew Raymer +**Date**: YYYY-MM-DD +**Status**: 🎯 **STATUS** - Brief description + +## Overview + +Brief description of the document's purpose and scope. + +## Current State + +Description of current situation or problem. + +## Implementation Plan + +### Phase 1: Foundation + +- [ ] Task 1 +- [ ] Task 2 + +## Next Steps + +1. **Review and approve plan** +2. **Begin implementation** +3. **Test and validate** + +--- + +**Status**: Ready for implementation +**Priority**: Medium +**Estimated Effort**: X days +**Dependencies**: None +**Stakeholders**: Development team +``` + +### Technical Specification Template + +```markdown +# Technical Specification: [Feature Name] + +**Author**: Matthew Raymer +**Date**: YYYY-MM-DD +**Status**: 🎯 **DRAFT** - Under Review + +## Overview + +Brief description of the technical specification. + +## Requirements + +### Functional Requirements + +- [ ] Requirement 1 +- [ ] Requirement 2 + +### Non-Functional Requirements + +- [ ] Performance requirement +- [ ] Security requirement + +## Technical Design + +### Architecture + +Description of the technical architecture. + +### Data Models + +```typescript +interface ExampleModel { + id: string; + name: string; + createdAt: Date; +} +``` + +### API Design + +```typescript +interface APIResponse { + success: boolean; + data: T; + error?: string; +} +``` + +## Testing Strategy + +- [ ] Unit tests +- [ ] Integration tests +- [ ] E2E tests + +--- + +**Status**: Draft +**Priority**: High +**Estimated Effort**: X days +**Dependencies**: None +**Stakeholders**: Development team + +``` + +## Content Examples + +### JSON Examples + +```json +{ + "property": "value", + "nested": { + "property": "value" + } +} +``` + +### Shell Commands + +```bash +# Command with comment +npm run build:web + +# Multi-line command +VITE_GIT_HASH=`git log -1 --pretty=format:%h` \ + vite build --config vite.config.web.mts +``` + +### TypeScript Examples + +```typescript +// Function with JSDoc +const getEnvironmentConfig = (env: string) => { + switch (env) { + case 'prod': + return { /* production settings */ }; + default: + return { /* development settings */ }; + } +}; +``` + +## File Structure Standards + +### Document Header + +```markdown +# Document Title + +**Author**: Matthew Raymer +**Date**: YYYY-MM-DD +**Status**: 🎯 **STATUS** - Brief description + +## Overview + +Brief description of the document's purpose and scope. +``` + +### Section Organization + +Standard sections: Overview, Current State, Implementation Plan, +Technical Details, Testing & Validation, Next Steps + +## Common Patterns + +Standard implementation plans follow Phase 1 (Foundation), Phase 2 +(Features), Phase 3 (Testing & Polish) structure. + +## Model Implementation Checklist + +### Before Using Templates + +- [ ] **Template Selection**: Choose appropriate template for document type +- [ ] **Structure Review**: Understand required sections and organization +- [ ] **Content Planning**: Plan what information goes in each section +- [ ] **Audience Analysis**: Ensure template matches target audience needs + +### During Template Usage + +- [ ] **Section Completion**: Fill in all required sections completely +- [ ] **Example Integration**: Include relevant code examples and patterns +- [ ] **Formatting Consistency**: Apply markdown standards from core rules +- [ ] **Cross-references**: Link to related documentation and resources + +### After Template Usage + +- [ ] **Content Review**: Verify all sections contain appropriate content +- [ ] **Formatting Check**: Run `npm run markdown:check` for compliance +- [ ] **Template Validation**: Confirm document follows template structure +- [ ] **Quality Assessment**: Ensure content meets project standards + +### Template-Specific Requirements + +- [ ] **Standard Documents**: Include all required metadata and sections +- [ ] **Technical Specs**: Complete all requirement and design sections +- [ ] **Implementation Plans**: Define clear phases and milestones +- [ ] **Examples**: Provide relevant, working code examples + +--- + +**See also**: + +- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards +- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows + +**Status**: Active templates and examples +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: markdown_core.mdc +**Stakeholders**: Documentation team, Development team diff --git a/.cursor/rules/docs/markdown_workflow.mdc b/.cursor/rules/docs/markdown_workflow.mdc new file mode 100644 index 00000000..0afadd2c --- /dev/null +++ b/.cursor/rules/docs/markdown_workflow.mdc @@ -0,0 +1,168 @@ +# Markdown Workflow & Validation + +> **Agent role**: Reference this file for markdown validation rules, +> enforcement procedures, and workflow management. + +## Markdownlint Configuration + +### Core Rules + +```json +{ + "MD013": { "line_length": 80, "code_blocks": false }, + "MD012": true, + "MD022": true, + "MD031": true, + "MD032": true, + "MD047": true, + "MD009": true, + "MD004": { "style": "dash" } +} +``` + +### Rule Explanations + +- **MD013**: Line length (80 chars, disabled for code blocks) +- **MD012**: No multiple consecutive blank lines +- **MD022**: Headings should be surrounded by blank lines +- **MD031**: Fenced code blocks should be surrounded by blank lines +- **MD032**: Lists should be surrounded by blank lines +- **MD047**: Files should end with a single newline +- **MD009**: No trailing spaces +- **MD004**: Consistent list markers (dash style) + +## Validation Commands + +### Check All MDC Files + +```bash +npm run markdown:check +``` + +### Auto-fix Formatting Issues + +```bash +npm run markdown:fix +``` + +### Check Single File + +```bash +npx markdownlint-cli2 .cursor/rules/filename.mdc +``` + +## Enforcement Workflow + +### Pre-commit Hooks + +- **Automatic**: `lint-staged` runs `markdownlint-cli2 --fix` on all + staged `.mdc` files +- **Result**: Files are automatically formatted before commit +- **Blocking**: Commits with unfixable violations are blocked + +### CI/CD Integration + +- **Build Pipeline**: Include markdownlint in automated builds +- **Quality Reports**: Generate documentation quality metrics +- **Build Failure**: Fail builds with critical violations + +### Team Guidelines + +- **PR Requirements**: All documentation PRs must pass markdownlint +- **Templates**: Use provided templates for new documents +- **Patterns**: Follow established patterns for consistency +- **Auto-fixing**: Let automation handle formatting, focus on content + +## Quality Assurance + +### Validation Checklist + +- [ ] All files pass `npm run markdown:check` +- [ ] Line length under 80 characters +- [ ] Proper blank line spacing around elements +- [ ] No trailing spaces +- [ ] Consistent list markers +- [ ] Proper heading hierarchy +- [ ] Code blocks have language specification + +### Common Issues & Fixes + +#### Trailing Spaces + +```bash +# Remove trailing spaces +sed -i 's/[[:space:]]*$//' .cursor/rules/**/*.mdc +``` + +#### Multiple Blank Lines + +```bash +# Remove multiple blank lines +sed -i '/^$/N;/^\n$/D' .cursor/rules/**/*.mdc +``` + +#### Missing Newlines + +```bash +# Add newline at end if missing +find .cursor/rules -name "*.mdc" -exec sed -i -e '$a\' {} \; +``` + +## Integration Points + +### Git Workflow + +1. **Edit**: Make changes to MDC files +2. **Stage**: `git add .cursor/rules/filename.mdc` +3. **Auto-fix**: `lint-staged` runs `markdownlint-cli2 --fix` +4. **Commit**: Changes are committed with perfect formatting + +### Development Workflow + +1. **Create/Edit**: Use templates from `markdown_templates.mdc` +2. **Validate**: Run `npm run markdown:check` before committing +3. **Auto-fix**: Use `npm run markdown:fix` for bulk fixes +4. **Review**: Ensure content quality, not just formatting + +## Model Implementation Checklist + +### Before Starting Workflow + +- [ ] **Configuration Review**: Understand markdownlint rules and settings +- [ ] **Tool Availability**: Ensure markdownlint-cli2 is installed and working +- [ ] **File Scope**: Identify which files need validation or fixing +- [ ] **Backup Strategy**: Consider backing up files before bulk operations + +### During Workflow Execution + +- [ ] **Validation First**: Run `npm run markdown:check` to identify issues +- [ ] **Issue Analysis**: Review and understand each validation error +- [ ] **Auto-fix Application**: Use `npm run markdown:fix` for automatic fixes +- [ ] **Manual Review**: Check files that couldn't be auto-fixed + +### After Workflow Completion + +- [ ] **Final Validation**: Confirm all files pass `npm run markdown:check` +- [ ] **Quality Review**: Verify formatting meets project standards +- [ ] **Documentation Update**: Update any related documentation or guides +- [ ] **Team Communication**: Share workflow results and any manual fixes needed + +### Workflow-Specific Requirements + +- [ ] **Pre-commit Hooks**: Ensure lint-staged configuration is working +- [ ] **CI/CD Integration**: Verify build pipeline includes markdown validation +- [ ] **Team Guidelines**: Confirm all team members understand the workflow +- [ ] **Error Resolution**: Document common issues and their solutions + +--- + +**See also**: + +- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards +- `.cursor/rules/docs/markdown_templates.mdc` for document templates + +**Status**: Active workflow and validation +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: markdown_core.mdc, markdown_templates.mdc +**Stakeholders**: Development team, Documentation team diff --git a/.cursor/rules/features/camera-implementation.mdc b/.cursor/rules/features/camera-implementation.mdc index afeb0e28..78c90e55 100644 --- a/.cursor/rules/features/camera-implementation.mdc +++ b/.cursor/rules/features/camera-implementation.mdc @@ -1,7 +1,3 @@ ---- -description: when dealing with cameras in the application -alwaysApply: false ---- # Camera Implementation Documentation ## Overview @@ -10,6 +6,7 @@ This document describes how camera functionality is implemented across the TimeSafari application. The application uses cameras for two main purposes: 1. QR Code scanning + 2. Photo capture ## Components @@ -21,17 +18,25 @@ Primary component for QR code scanning in web browsers. **Key Features:** - Uses `qrcode-stream` for web-based QR scanning + - Supports both front and back cameras + - Provides real-time camera status feedback + - Implements error handling with user-friendly messages + - Includes camera switching functionality **Camera Access Flow:** 1. Checks for camera API availability + 2. Enumerates available video devices + 3. Requests camera permissions + 4. Initializes camera stream with preferred settings + 5. Handles various error conditions with specific messages ### PhotoDialog.vue @@ -41,8 +46,11 @@ Component for photo capture and selection. **Key Features:** - Cross-platform photo capture interface + - Image cropping capabilities + - File selection fallback + - Unified interface for different platforms ## Services @@ -56,8 +64,11 @@ Web-based implementation of QR scanning. **Key Methods:** - `checkPermissions()`: Verifies camera permission status + - `requestPermissions()`: Requests camera access + - `isSupported()`: Checks for camera API support + - Handles various error conditions with specific messages #### CapacitorQRScanner @@ -67,8 +78,11 @@ Native implementation using Capacitor's MLKit. **Key Features:** - Uses `@capacitor-mlkit/barcode-scanning` + - Supports both front and back cameras + - Implements permission management + - Provides continuous scanning capability ### Platform Services @@ -80,7 +94,9 @@ Web-specific implementation of platform features. **Camera Capabilities:** - Uses HTML5 file input with capture attribute + - Falls back to file selection if camera unavailable + - Processes captured images for consistent format #### CapacitorPlatformService @@ -90,133 +106,58 @@ Native implementation using Capacitor. **Camera Features:** - Uses `Camera.getPhoto()` for native camera access + - Supports image editing + - Configures high-quality image capture + - Handles base64 image processing #### ElectronPlatformService Desktop implementation (currently unimplemented). -**Status:** - -- Camera functionality not yet implemented -- Planned to use Electron's media APIs - -## Platform-Specific Considerations - -### iOS - -- Requires `NSCameraUsageDescription` in Info.plist -- Supports both front and back cameras -- Implements proper permission handling - -### Android - -- Requires camera permissions in manifest -- Supports both front and back cameras -- Handles permission requests through Capacitor - -### Web - -- Requires HTTPS for camera access -- Implements fallback mechanisms -- Handles browser compatibility issues - -## Error Handling - -### Common Error Scenarios - -1. No camera found -2. Permission denied -3. Camera in use by another application -4. HTTPS required -5. Browser compatibility issues - -### Error Response - -- User-friendly error messages -- Troubleshooting tips -- Clear instructions for resolution -- Platform-specific guidance - -## Security Considerations - -### Permission Management - -- Explicit permission requests -- Permission state tracking -- Graceful handling of denied permissions - -### Data Handling - -- Secure image processing -- Proper cleanup of camera resources -- No persistent storage of camera data - -## Best Practices - -### Camera Access - -1. Always check for camera availability -2. Request permissions explicitly -3. Handle all error conditions -4. Provide clear user feedback -5. Implement proper cleanup - -### Performance - -1. Optimize camera resolution -2. Implement proper resource cleanup -3. Handle camera switching efficiently -4. Manage memory usage +--- -### User Experience +**See also**: -1. Clear status indicators -2. Intuitive camera controls -3. Helpful error messages -4. Smooth camera switching -5. Responsive UI feedback +- `.cursor/rules/features/camera_technical.mdc` for -## Future Improvements + detailed technical implementation -### Planned Enhancements +- `.cursor/rules/features/camera_platforms.mdc` for platform-specific details -1. Implement Electron camera support -2. Add advanced camera features -3. Improve error handling -4. Enhance user feedback -5. Optimize performance +**Status**: Active camera implementation overview +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, Camera feature team -### Known Issues +- iOS and Android devices -1. Electron camera implementation pending -2. Some browser compatibility limitations -3. Platform-specific quirks to address +- Desktop platforms -## Dependencies +- Various network conditions -### Key Packages +## Model Implementation Checklist -- `@capacitor-mlkit/barcode-scanning` -- `qrcode-stream` -- `vue-picture-cropper` -- Platform-specific camera APIs +### Before Camera Implementation -## Testing +- [ ] **Platform Analysis**: Understand camera requirements across all platforms +- [ ] **Feature Planning**: Plan QR scanning and photo capture features +- [ ] **Service Planning**: Plan camera service architecture +- [ ] **Testing Strategy**: Plan testing across web, mobile, and desktop -### Test Scenarios +### During Camera Implementation -1. Permission handling -2. Camera switching -3. Error conditions -4. Platform compatibility -5. Performance metrics +- [ ] **Component Development**: Implement QRScannerDialog and PhotoDialog +- [ ] **Service Implementation**: Implement platform-specific camera services +- [ ] **Permission Handling**: Implement proper camera permission management +- [ ] **Error Handling**: Implement graceful error handling for camera failures -### Test Environment +### After Camera Implementation -- Multiple browsers -- iOS and Android devices -- Desktop platforms -- Various network conditions +- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms +- [ ] **Feature Validation**: Verify QR scanning and photo capture work correctly +- [ ] **Performance Testing**: Ensure camera performance meets requirements +- [ ] **Documentation Update**: Update camera implementation documentation diff --git a/.cursor/rules/features/camera_platforms.mdc b/.cursor/rules/features/camera_platforms.mdc new file mode 100644 index 00000000..a7a35664 --- /dev/null +++ b/.cursor/rules/features/camera_platforms.mdc @@ -0,0 +1,225 @@ +# Camera Platform-Specific Implementation + +> **Agent role**: + Reference this file for platform-specific camera implementation details. + +## Web Platform + +### Implementation Details + +- Uses `getUserMedia` API for camera access + +- Implements fallback to file input if camera unavailable + +- Handles browser compatibility issues + +- Requires HTTPS for camera access + +### Browser Support + +- Chrome: Full support + +- Firefox: Full support + +- Safari: Limited support + +- Edge: Full support + +### Fallback Mechanisms + +1. Camera access via getUserMedia + +2. File input for image upload + +3. Drag and drop support + +4. Clipboard paste support + +## Mobile Platform (Capacitor) + +### iOS Implementation + +- Uses `@capacitor-mlkit/barcode-scanning` + +- Implements proper permission handling + +- Supports both front and back cameras + +- Handles camera switching + +### Android Implementation + +- Uses `@capacitor-mlkit/barcode-scanning` + +- Implements proper permission handling + +- Supports both front and back cameras + +- Handles camera switching + +### Permission Handling + +- Camera permissions requested at runtime + +- Permission state tracked and cached + +- Graceful handling of denied permissions + +- Clear user guidance for enabling permissions + +## Desktop Platform (Electron) + +### Current Status + +- Camera implementation pending + +- Will use platform-specific APIs + +- Requires proper permission handling + +- Will support both built-in and external cameras + +### Planned Implementation + +- Native camera access via Electron + +- Platform-specific camera APIs + +- Proper permission handling + +- Camera switching support + +## Platform Detection + +### Implementation + +- Uses `PlatformServiceFactory` for platform detection + +- Implements platform-specific camera services + +- Handles platform-specific error conditions + +- Provides platform-specific user guidance + +### Service Selection + +- Web: `WebPlatformService` + +- Mobile: `CapacitorPlatformService` + +- Desktop: `ElectronPlatformService` + +## Cross-Platform Compatibility + +### Common Interface + +- Unified camera service interface + +- Platform-specific implementations + +- Consistent error handling + +- Unified user experience + +### Feature Parity + +- Core camera functionality across platforms + +- Platform-specific optimizations + +- Consistent user interface + +- Unified error messages + +## Platform-Specific Features + +### Web + +- Browser-based camera access + +- File upload fallback + +- Drag and drop support + +- Clipboard paste support + +### Mobile + +- Native camera access + +- Barcode scanning + +- Photo capture + +- Camera switching + +### Desktop + +- Native camera access (planned) + +- External camera support (planned) + +- Advanced camera controls (planned) + +## Testing Strategy + +### Platform Coverage + +- Web: Multiple browsers + +- Mobile: iOS and Android devices + +- Desktop: Windows, macOS, Linux + +### Test Scenarios + +- Permission handling + +- Camera access + +- Error conditions + +- Platform compatibility + +- Performance metrics + +--- + +**See also**: + +- `.cursor/rules/features/camera-implementation.mdc` for + + core implementation overview + +- `.cursor/rules/features/camera_technical.mdc` for + + technical implementation details + +**Status**: Active platform-specific implementation guide +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: camera-implementation.mdc +**Stakeholders**: Development team, Platform team + +## Model Implementation Checklist + +### Before Camera Platform Implementation + +- [ ] **Platform Analysis**: Identify target platforms and their camera capabilities +- [ ] **Feature Planning**: Plan platform-specific camera features +- [ ] **Integration Planning**: Plan integration with existing camera systems +- [ ] **Testing Strategy**: Plan testing across all target platforms + +### During Camera Platform Implementation + +- [ ] **Platform Services**: Implement platform-specific camera functionality +- [ ] **Feature Development**: Implement planned camera features for each platform +- [ ] **Integration**: Integrate with existing camera infrastructure +- [ ] **Performance Optimization**: Optimize camera performance for each platform + +### After Camera Platform Implementation + +- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms +- [ ] **Feature Validation**: Verify all planned features work correctly +- [ ] **Performance Testing**: Ensure camera performance meets requirements +- [ ] **Documentation Update**: Update platform-specific camera documentation diff --git a/.cursor/rules/features/camera_technical.mdc b/.cursor/rules/features/camera_technical.mdc new file mode 100644 index 00000000..4f69a3de --- /dev/null +++ b/.cursor/rules/features/camera_technical.mdc @@ -0,0 +1,203 @@ +# Camera Technical Implementation — Details and Best Practices + +> **Agent role**: Reference this file for + detailed technical implementation when working with camera features. + +## Platform-Specific Considerations + +### iOS + +- Requires `NSCameraUsageDescription` in Info.plist + +- Supports both front and back cameras + +- Implements proper permission handling + +### Android + +- Requires camera permissions in manifest + +- Supports both front and back cameras + +- Handles permission requests through Capacitor + +### Web + +- Requires HTTPS for camera access + +- Implements fallback mechanisms + +- Handles browser compatibility issues + +## Error Handling + +### Common Error Scenarios + +1. No camera found + +2. Permission denied + +3. Camera in use by another application + +4. HTTPS required + +5. Browser compatibility issues + +### Error Response + +- User-friendly error messages + +- Troubleshooting tips + +- Clear instructions for resolution + +- Platform-specific guidance + +## Security Considerations + +### Permission Management + +- Explicit permission requests + +- Permission state tracking + +- Graceful handling of denied permissions + +### Data Handling + +- Secure image processing + +- Proper cleanup of camera resources + +- No persistent storage of camera data + +## Best Practices + +### Camera Access + +1. Always check for camera availability + +2. Request permissions explicitly + +3. Handle all error conditions + +4. Provide clear user feedback + +5. Implement proper cleanup + +### Performance + +1. Optimize camera resolution + +2. Implement proper resource cleanup + +3. Handle camera switching efficiently + +4. Manage memory usage + +### User Experience + +1. Clear status indicators + +2. Intuitive camera controls + +3. Helpful error messages + +4. Smooth camera switching + +5. Responsive UI feedback + +## Future Improvements + +### Planned Enhancements + +1. Implement Electron camera support + +2. Add advanced camera features + +3. Improve error handling + +4. Enhance user feedback + +5. Optimize performance + +### Known Issues + +1. Electron camera implementation pending + +2. Some browser compatibility limitations + +3. Platform-specific quirks to address + +## Dependencies + +### Key Packages + +- `@capacitor-mlkit/barcode-scanning` + +- `qrcode-stream` + +- `vue-picture-cropper` + +- Platform-specific camera APIs + +## Testing + +### Test Scenarios + +1. Permission handling + +2. Camera switching + +3. Error conditions + +4. Platform compatibility + +5. Performance metrics + +### Test Environment + +- Multiple browsers + +- iOS and Android devices + +- Desktop platforms + +--- + +**See also**: + +- `.cursor/rules/features/camera-implementation.mdc` for + + core implementation overview + +- `.cursor/rules/features/camera_platforms.mdc` for platform-specific details + +**Status**: Active technical implementation guide +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: camera-implementation.mdc +**Stakeholders**: Development team, Camera feature team + +## Model Implementation Checklist + +### Before Camera Implementation + +- [ ] **Platform Analysis**: Identify target platforms and camera capabilities +- [ ] **Permission Planning**: Plan permission handling for camera access +- [ ] **Dependency Review**: Review required camera packages and APIs +- [ ] **Testing Strategy**: Plan testing across multiple platforms + +### During Camera Implementation + +- [ ] **Platform Services**: Implement platform-specific camera services +- [ ] **Permission Handling**: Implement proper camera permission handling +- [ ] **Error Handling**: Implement graceful error handling for camera failures +- [ ] **Performance Optimization**: Optimize camera performance and responsiveness + +### After Camera Implementation + +- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms +- [ ] **Permission Testing**: Test permission handling and user feedback +- [ ] **Performance Validation**: Verify camera performance meets requirements +- [ ] **Documentation Update**: Update camera technical documentation diff --git a/.cursor/rules/harbor_pilot_universal.mdc b/.cursor/rules/harbor_pilot_universal.mdc deleted file mode 100644 index b3714c6c..00000000 --- a/.cursor/rules/harbor_pilot_universal.mdc +++ /dev/null @@ -1,206 +0,0 @@ ---- -alwaysApply: true -inherits: base_context.mdc ---- -```json -{ - "coaching_level": "standard", - "socratic_max_questions": 2, - "verbosity": "concise", - "timebox_minutes": 10, - "format_enforcement": "strict" -} -``` - -# Harbor Pilot — Universal Directive for Human-Facing Technical Guides - -**Author**: System/Shared -**Date**: 2025-08-21 (UTC) -**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human Competence First* - -> **Alignment with Base Context** -> - **Purpose fit**: Prioritizes human competence and collaboration while delivering reproducible artifacts. -> - **Output Contract**: This directive **adds universal constraints** for any technical topic while **inheriting** the Base Context contract sections. -> - **Toggles honored**: Uses the same toggle semantics; defaults above can be overridden by the caller. - ---- - -## Objective -Produce a **developer-grade, reproducible guide** for any technical topic that onboards a competent practitioner **without meta narration** and **with evidence-backed steps**. - -## Scope & Constraints -- **One Markdown document** as the deliverable. -- Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid “today/yesterday”. -- Include at least **one diagram** (Mermaid preferred). Choose the most fitting type: - - `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`, `gantt` (timelines), or `classDiagram` (schemas). -- Provide runnable examples where applicable: - - **APIs**: `curl` + one client library (e.g., `httpx` for Python). - - **CLIs**: literal command blocks and expected output snippets. - - **Code**: minimal, self-contained samples (language appropriate). -- Cite **evidence** for *Works/Doesn’t* items (timestamps, filenames, line numbers, IDs/status codes, or logs). -- If something is unknown, output `TODO:` — **never invent**. - -## Required Sections (extends Base Output Contract) -Follow this exact order **after** the Base Contract’s **Objective → Result → Use/Run** headers: - -1. **Context & Scope** - - Problem statement, audience, in/out-of-scope bullets. -2. **Artifacts & Links** - - Repos/PRs, design docs, datasets/HARs/pcaps, scripts/tools, dashboards. -3. **Environment & Preconditions** - - OS/runtime, versions/build IDs, services/endpoints/URLs, credentials/auth mode (describe acquisition, do not expose secrets). -4. **Architecture / Process Overview** - - Short prose + **one diagram** selected from the list above. -5. **Interfaces & Contracts (choose one)** - - **API-based**: Endpoint table (*Step, Method, Path/URL, Auth, Key Headers/Params, Sample Req/Resp ref*). - - **Data/Files**: I/O contract table (*Source, Format, Schema/Columns, Size, Validation rules*). - - **Systems/Hardware**: Interfaces table (*Port/Bus, Protocol, Voltage/Timing, Constraints*). -6. **Repro: End-to-End Procedure** - - Minimal copy-paste steps with code/commands and **expected outputs**. -7. **What Works (with Evidence)** - - Each item: **Time (UTC)** • **Artifact/Req IDs** • **Status/Result** • **Where to verify**. -8. **What Doesn’t (Evidence & Hypotheses)** - - Each failure: locus (file/endpoint/module), evidence snippet; short hypothesis and **next probe**. -9. **Risks, Limits, Assumptions** - - SLOs/limits, rate/size caps, security boundaries (CORS/CSRF/ACLs), retries/backoff/idempotency patterns. -10. **Next Steps (Owner • Exit Criteria • Target Date)** - - Actionable, assigned, and time-bound. -11. **References** - - Canonical docs, specs, tickets, prior analyses. - -> **Competence Hooks (per Base Context; keep lightweight):** -> - *Why this works* (≤3 bullets) — core invariants or guarantees. -> - *Common pitfalls* (≤3 bullets) — the traps we saw in evidence. -> - *Next skill unlock* (1 line) — the next capability to implement/learn. -> - *Teach-back* (1 line) — prompt the reader to restate the flow/architecture. - -> **Collaboration Hooks (per Base Context):** -> - Name reviewers for **Interfaces & Contracts** and the **diagram**. -> - Short **sign-off checklist** before merging/publishing the guide. - -## Do / Don’t (Base-aligned) -- **Do** quantify progress only against a defined scope with acceptance criteria. -- **Do** include minimal sample payloads/headers or I/O schemas; redact sensitive values. -- **Do** keep commentary lean; if timeboxed, move depth to **Deferred for depth**. -- **Don’t** use marketing language or meta narration (“Perfect!”, “tool called”, “new chat”). -- **Don’t** include IDE-specific chatter or internal rules unrelated to the task. - -## Validation Checklist (self-check before returning) -- [ ] All Required Sections present and ordered. -- [ ] Diagram compiles (basic Mermaid syntax) and fits the problem. -- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for each endpoint. -- [ ] Repro section includes commands/code **and expected outputs**. -- [ ] Every Works/Doesn’t item has **UTC timestamp**, **status/result**, and **verifiable evidence**. -- [ ] Next Steps include **Owner**, **Exit Criteria**, **Target Date**. -- [ ] Unknowns are `TODO:` — no fabrication. -- [ ] Base **Output Contract** sections satisfied (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References). - -## Universal Template (fill-in) -```markdown -# — Working Notes (As of YYYY-MM-DDTHH:MMZ) - -## Objective -<one line> - -## Result -<link to the produced guide file or say “this document”> - -## Use/Run -<how to apply/test and where to run samples> - -## Context & Scope -- Audience: <role(s)> -- In scope: <bullets> -- Out of scope: <bullets> - -## Artifacts & Links -- Repo/PR: <link> -- Data/Logs: <paths or links> -- Scripts/Tools: <paths> -- Dashboards: <links> - -## Environment & Preconditions -- OS/Runtime: <details> -- Versions/Builds: <list> -- Services/Endpoints: <list> -- Auth mode: <Bearer/Session/Keys + how acquired> - -## Architecture / Process Overview -<short prose> -```mermaid -<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt | classDiagram> -``` - -## Interfaces & Contracts -### If API-based -| Step | Method | Path/URL | Auth | Key Headers/Params | Sample | -|---|---|---|---|---|---| -| <…> | <…> | <…> | <…> | <…> | below | - -### If Data/Files -| Source | Format | Schema/Columns | Size | Validation | -|---|---|---|---|---| -| <…> | <…> | <…> | <…> | <…> | - -### If Systems/Hardware -| Interface | Protocol | Timing/Voltage | Constraints | Notes | -|---|---|---|---|---| -| <…> | <…> | <…> | <…> | <…> | - -## Repro: End-to-End Procedure -```bash -# commands / curl examples (redacted where necessary) -``` -```python -# minimal client library example (language appropriate) -``` -> Expected output: <snippet/checks> - -## What Works (Evidence) -- ✅ <short statement> - - **Time**: <YYYY-MM-DDTHH:MMZ> - - **Evidence**: file/line/log or request id/status - - **Verify at**: <where> - -## What Doesn’t (Evidence & Hypotheses) -- ❌ <short failure> at `<component/endpoint/file>` - - **Time**: <YYYY-MM-DDTHH:MMZ> - - **Evidence**: <snippet/id/status> - - **Hypothesis**: <short> - - **Next probe**: <short> - -## Risks, Limits, Assumptions -<bullets: limits, security boundaries, retries/backoff, idempotency, SLOs> - -## Next Steps -| Owner | Task | Exit Criteria | Target Date (UTC) | -|---|---|---|---| -| <name> | <action> | <measurable outcome> | <YYYY-MM-DD> | - -## References -<links/titles> - -## Competence Hooks -- *Why this works*: <≤3 bullets> -- *Common pitfalls*: <≤3 bullets> -- *Next skill unlock*: <1 line> -- *Teach-back*: <1 line> - -## Collaboration Hooks -- Reviewers: <names/roles> -- Sign-off checklist: <≤5 checks> - -## Assumptions & Limits -<bullets> - -## Deferred for depth -<park deeper material here to respect timeboxing> -``` - ---- - -**Notes for Implementers:** -- Respect Base *Do-Not* (no filler, no invented facts, no censorship). -- Prefer clarity over completeness when timeboxed; capture unknowns explicitly. -- Apply historical comment management rules (see `.cursor/rules/historical_comment_management.mdc`) -- Apply realistic time estimation rules (see `.cursor/rules/realistic_time_estimation.mdc`) \ No newline at end of file diff --git a/.cursor/rules/historical_comment_management.mdc b/.cursor/rules/historical_comment_management.mdc deleted file mode 100644 index 4f78f38a..00000000 --- a/.cursor/rules/historical_comment_management.mdc +++ /dev/null @@ -1,236 +0,0 @@ ---- -description: when comments are generated by the model -alwaysApply: false ---- -# Historical Comment Management — Harbor Pilot Directive - -> **Agent role**: When encountering historical comments about removed methods, deprecated patterns, or architectural changes, apply these guidelines to maintain code clarity and developer guidance. - -## 🎯 Purpose - -Historical comments should either be **removed entirely** or **transformed into actionable guidance** for future developers. Avoid keeping comments that merely state what was removed without explaining why or what to do instead. - -## 📋 Decision Framework - -### Remove Historical Comments When: -- **Obsolete Information**: Comment describes functionality that no longer exists -- **No Action Required**: Comment doesn't help future developers make decisions -- **Outdated Context**: Comment refers to old patterns that are no longer relevant -- **Self-Evident**: The current code clearly shows the current approach - -### Transform Historical Comments When: -- **Architectural Context**: The change represents a significant pattern shift -- **Migration Guidance**: Future developers might need to understand the evolution -- **Decision Rationale**: The "why" behind the change is still relevant -- **Alternative Approaches**: The comment can guide future implementation choices - -## 🔄 Transformation Patterns - -### 1. From Removal Notice to Migration Note -```typescript -// ❌ REMOVE THIS -// turnOffNotifyingFlags method removed - notification state is now managed by NotificationSection component - -// ✅ TRANSFORM TO THIS -// Note: Notification state management has been migrated to NotificationSection component -// which handles its own lifecycle and persistence via PlatformServiceMixin -``` - -### 2. From Deprecation Notice to Implementation Guide -```typescript -// ❌ REMOVE THIS -// This will be handled by the NewComponent now -// No need to call oldMethod() as it's no longer needed - -// ✅ TRANSFORM TO THIS -// Note: This functionality has been migrated to NewComponent -// which provides better separation of concerns and testability -``` - -### 3. From Historical Note to Architectural Context -```typescript -// ❌ REMOVE THIS -// Old approach: used direct database calls -// New approach: uses service layer - -// ✅ TRANSFORM TO THIS -// Note: Database access has been abstracted through service layer -// for better testability and platform independence -``` - -## 🚫 Anti-Patterns to Remove - -- Comments that only state what was removed -- Comments that don't explain the current approach -- Comments that reference non-existent methods -- Comments that are self-evident from the code -- Comments that don't help future decision-making - -## ✅ Best Practices - -### When Keeping Historical Context: -1. **Explain the "Why"**: Why was the change made? -2. **Describe the "What"**: What is the current approach? -3. **Provide Context**: When might this information be useful? -4. **Use Actionable Language**: Guide future decisions, not just document history - -### When Removing Historical Context: -1. **Verify Obsoleteness**: Ensure the information is truly outdated -2. **Check for Dependencies**: Ensure no other code references the old approach -3. **Update Related Docs**: If removing from code, consider adding to documentation -4. **Preserve in Git History**: The change is preserved in version control - -## 🔍 Implementation Checklist - -- [ ] Identify historical comments about removed/deprecated functionality -- [ ] Determine if comment provides actionable guidance -- [ ] Transform useful comments into migration notes or architectural context -- [ ] Remove comments that are purely historical without guidance value -- [ ] Ensure remaining comments explain current approach and rationale -- [ ] Update related documentation if significant context is removed - -## 📚 Examples - -### Good Historical Comment (Keep & Transform) -```typescript -// Note: Database access has been migrated from direct IndexedDB calls to PlatformServiceMixin -// This provides better platform abstraction and consistent error handling across web/mobile/desktop -// When adding new database operations, use this.$getContact(), this.$saveSettings(), etc. -``` - -### Bad Historical Comment (Remove) -```typescript -// Old method getContactFromDB() removed - now handled by PlatformServiceMixin -// No need to call the old method anymore -``` - -## 🎯 Integration with Harbor Pilot - -This rule works in conjunction with: -- **Component Creation Ideals**: Maintains architectural consistency -- **Migration Patterns**: Documents evolution of patterns -- **Code Review Guidelines**: Ensures comments provide value - -## 📝 Version History - -### v1.0.0 (2025-08-21) -- Initial creation based on notification system cleanup -- Established decision framework for historical comment management -- Added transformation patterns and anti-patterns -- Integrated with existing Harbor Pilot architecture rules -# Historical Comment Management — Harbor Pilot Directive - -> **Agent role**: When encountering historical comments about removed methods, deprecated patterns, or architectural changes, apply these guidelines to maintain code clarity and developer guidance. - -## 🎯 Purpose - -Historical comments should either be **removed entirely** or **transformed into actionable guidance** for future developers. Avoid keeping comments that merely state what was removed without explaining why or what to do instead. - -## 📋 Decision Framework - -### Remove Historical Comments When: -- **Obsolete Information**: Comment describes functionality that no longer exists -- **No Action Required**: Comment doesn't help future developers make decisions -- **Outdated Context**: Comment refers to old patterns that are no longer relevant -- **Self-Evident**: The current code clearly shows the current approach - -### Transform Historical Comments When: -- **Architectural Context**: The change represents a significant pattern shift -- **Migration Guidance**: Future developers might need to understand the evolution -- **Decision Rationale**: The "why" behind the change is still relevant -- **Alternative Approaches**: The comment can guide future implementation choices - -## 🔄 Transformation Patterns - -### 1. From Removal Notice to Migration Note -```typescript -// ❌ REMOVE THIS -// turnOffNotifyingFlags method removed - notification state is now managed by NotificationSection component - -// ✅ TRANSFORM TO THIS -// Note: Notification state management has been migrated to NotificationSection component -// which handles its own lifecycle and persistence via PlatformServiceMixin -``` - -### 2. From Deprecation Notice to Implementation Guide -```typescript -// ❌ REMOVE THIS -// This will be handled by the NewComponent now -// No need to call oldMethod() as it's no longer needed - -// ✅ TRANSFORM TO THIS -// Note: This functionality has been migrated to NewComponent -// which provides better separation of concerns and testability -``` - -### 3. From Historical Note to Architectural Context -```typescript -// ❌ REMOVE THIS -// Old approach: used direct database calls -// New approach: uses service layer - -// ✅ TRANSFORM TO THIS -// Note: Database access has been abstracted through service layer -// for better testability and platform independence -``` - -## 🚫 Anti-Patterns to Remove - -- Comments that only state what was removed -- Comments that don't explain the current approach -- Comments that reference non-existent methods -- Comments that are self-evident from the code -- Comments that don't help future decision-making - -## ✅ Best Practices - -### When Keeping Historical Context: -1. **Explain the "Why"**: Why was the change made? -2. **Describe the "What"**: What is the current approach? -3. **Provide Context**: When might this information be useful? -4. **Use Actionable Language**: Guide future decisions, not just document history - -### When Removing Historical Context: -1. **Verify Obsoleteness**: Ensure the information is truly outdated -2. **Check for Dependencies**: Ensure no other code references the old approach -3. **Update Related Docs**: If removing from code, consider adding to documentation -4. **Preserve in Git History**: The change is preserved in version control - -## 🔍 Implementation Checklist - -- [ ] Identify historical comments about removed/deprecated functionality -- [ ] Determine if comment provides actionable guidance -- [ ] Transform useful comments into migration notes or architectural context -- [ ] Remove comments that are purely historical without guidance value -- [ ] Ensure remaining comments explain current approach and rationale -- [ ] Update related documentation if significant context is removed - -## 📚 Examples - -### Good Historical Comment (Keep & Transform) -```typescript -// Note: Database access has been migrated from direct IndexedDB calls to PlatformServiceMixin -// This provides better platform abstraction and consistent error handling across web/mobile/desktop -// When adding new database operations, use this.$getContact(), this.$saveSettings(), etc. -``` - -### Bad Historical Comment (Remove) -```typescript -// Old method getContactFromDB() removed - now handled by PlatformServiceMixin -// No need to call the old method anymore -``` - -## 🎯 Integration with Harbor Pilot - -This rule works in conjunction with: -- **Component Creation Ideals**: Maintains architectural consistency -- **Migration Patterns**: Documents evolution of patterns -- **Code Review Guidelines**: Ensures comments provide value - -## 📝 Version History - -### v1.0.0 (2025-08-21) -- Initial creation based on notification system cleanup -- Established decision framework for historical comment management -- Added transformation patterns and anti-patterns -- Integrated with existing Harbor Pilot architecture rules diff --git a/.cursor/rules/less_complex.mdc b/.cursor/rules/less_complex.mdc deleted file mode 100644 index 822efbea..00000000 --- a/.cursor/rules/less_complex.mdc +++ /dev/null @@ -1,49 +0,0 @@ ---- -description: Enforce minimalist fixes for bugs/features; future-proofing requires prior discussion and strong evidence. -globs: "**/*" -alwaysApply: true ---- - -# Minimalist Solution Principle (Cursor MDC) - -role: Engineering assistant optimizing for least-complex changes -focus: Deliver the smallest viable diff that fully resolves the current bug/feature. Defer generalization unless justified with evidence. -language: Match repository languages and conventions - -## Rules -1. **Default to the least complex solution.** Fix the problem directly where it occurs; avoid new layers, indirection, or patterns unless strictly necessary. -2. **Keep scope tight.** Implement only what is needed to satisfy the acceptance criteria and tests for *this* issue. -3. **Avoid speculative abstractions.** Use the **Rule of Three**: don’t extract helpers/patterns until the third concrete usage proves the shape. -4. **No drive-by refactors.** Do not rename, reorder, or reformat unrelated code in the same change set. -5. **Minimize surface area.** Prefer local changes over cross-cutting rewires; avoid new public APIs unless essential. -6. **Be dependency-frugal.** Do not add packages or services for single, simple needs unless there’s a compelling, documented reason. -7. **Targeted tests only.** Add the smallest set of tests that prove the fix and guard against regression; don’t rewrite suites. -8. **Document the “why enough.”** Include a one-paragraph note explaining why this minimal solution is sufficient *now*. - -## Future-Proofing Requires Evidence + Discussion -Any added complexity “for the future” **must** include: -- A referenced discussion/ADR (or issue link) summarizing the decision. -- **Substantial evidence**, e.g.: - - Recurring incidents or tickets that this prevents (list IDs). - - Benchmarks or profiling showing a real bottleneck. - - Concrete upcoming requirements with dates/owners, not hypotheticals. - - Risk assessment comparing maintenance cost vs. expected benefit. -- A clear trade-off table showing why minimal won’t suffice. - -If this evidence is not available, **ship the minimal fix** and open a follow-up discussion item. - -## PR / Change Checklist (enforced by reviewer + model) -- [ ] Smallest diff that fully fixes the issue (attach `git diff --stat` if useful). -- [ ] No unrelated refactors or formatting. -- [ ] No new dependencies, or justification + ADR link provided. -- [ ] Abstractions only if ≥3 call sites or strong evidence says otherwise (cite). -- [ ] Targeted tests proving the fix/regression guard. -- [ ] Short “Why this is enough now” note in the PR description. -- [ ] Optional: “Future Work (non-blocking)” section listing deferred ideas. - -## Assistant Output Contract -When proposing a change, provide: -1. **Minimal Plan**: 3–6 bullet steps scoped to the immediate fix. -2. **Patch Sketch**: Focused diffs/snippets touching only necessary files. -3. **Risk & Rollback**: One paragraph each on risk, quick rollback, and test points. -4. **(If proposing complexity)**: Link/inline ADR summary + evidence + trade-offs; otherwise default to minimal. diff --git a/.cursor/rules/meta_bug_diagnosis.mdc b/.cursor/rules/meta_bug_diagnosis.mdc new file mode 100644 index 00000000..a919d583 --- /dev/null +++ b/.cursor/rules/meta_bug_diagnosis.mdc @@ -0,0 +1,172 @@ +# Meta-Rule: Bug Diagnosis + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Bug investigation workflow bundling + +## Purpose + +This meta-rule bundles all the rules needed for systematic bug investigation +and root cause analysis. Use this when bugs are reported, performance +issues occur, or unexpected behavior happens. + +## When to Use + +- **Bug Reports**: Investigating reported bugs or issues +- **Performance Issues**: Diagnosing slow performance or bottlenecks +- **Unexpected Behavior**: Understanding why code behaves unexpectedly +- **Production Issues**: Investigating issues in live environments +- **Test Failures**: Understanding why tests are failing +- **Integration Problems**: Diagnosing issues between components + +## Bundled Rules + +### **Investigation Process** + +- **`development/research_diagnostic.mdc`** - Systematic investigation + workflow with evidence collection and analysis +- **`development/investigation_report_example.mdc`** - Investigation + documentation templates and examples +- **`core/harbor_pilot_universal.mdc`** - Technical guide creation + for complex investigations + +### **Evidence Collection** + +- **`development/logging_standards.mdc`** - Logging implementation + standards for debugging and evidence collection +- **`development/time.mdc`** - Timestamp requirements and time + handling standards for evidence +- **`development/time_examples.mdc`** - Practical examples of + proper time handling in investigations + +### **Technical Context** + +- **`app/timesafari.mdc`** - Core application context and + architecture for understanding the system +- **`app/timesafari_platforms.mdc`** - Platform-specific + considerations and constraints + +## Workflow Sequence + +### **Phase 1: Initial Investigation (Start Here)** + +1. **Research Diagnostic** - Use `research_diagnostic.mdc` for + systematic investigation approach +2. **Evidence Collection** - Apply `logging_standards.mdc` and + `time.mdc` for proper evidence gathering +3. **Context Understanding** - Review `timesafari.mdc` for + application context + +### **Phase 2: Deep Investigation** + +1. **Platform Analysis** - Check `timesafari_platforms.mdc` for + platform-specific issues +2. **Technical Guide Creation** - Use `harbor_pilot_universal.mdc` + for complex investigation documentation +3. **Evidence Analysis** - Apply `time_examples.mdc` for proper + timestamp handling + +### **Phase 3: Documentation & Reporting** + +1. **Investigation Report** - Use `investigation_report_example.mdc` + for comprehensive documentation +2. **Root Cause Analysis** - Synthesize findings into actionable + insights + +## Success Criteria + +- [ ] **Root cause identified** with supporting evidence +- [ ] **Evidence properly collected** with timestamps and context +- [ ] **Investigation documented** using appropriate templates +- [ ] **Platform factors considered** in diagnosis +- [ ] **Reproduction steps documented** for verification +- [ ] **Impact assessment completed** with scope defined +- [ ] **Next steps identified** for resolution + +## Common Pitfalls + +- **Don't skip evidence collection** - leads to speculation +- **Don't ignore platform differences** - misses platform-specific issues +- **Don't skip documentation** - loses investigation insights +- **Don't assume root cause** - verify with evidence +- **Don't ignore time context** - misses temporal factors +- **Don't skip reproduction steps** - makes verification impossible + +## Integration Points + +### **With Other Meta-Rules** + +- **Feature Planning**: Use complexity assessment for investigation planning +- **Bug Fixing**: Investigation results feed directly into fix implementation +- **Feature Implementation**: Investigation insights inform future development + +### **With Development Workflow** + +- Investigation findings inform testing strategy +- Root cause analysis drives preventive measures +- Evidence collection improves logging standards + +## Feedback & Improvement + +### **Sub-Rule Ratings (1-5 scale)** + +- **Research Diagnostic**: ___/5 - Comments: _______________ +- **Investigation Report**: ___/5 - Comments: _______________ +- **Technical Guide Creation**: ___/5 - Comments: _______________ +- **Logging Standards**: ___/5 - Comments: _______________ +- **Time Standards**: ___/5 - Comments: _______________ + +### **Workflow Feedback** + +- **Investigation Effectiveness**: How well did the process help find root cause? +- **Missing Steps**: What investigation steps should be added? +- **Process Gaps**: Where did the workflow break down? + +### **Sub-Rule Improvements** + +- **Clarity Issues**: Which rules were unclear or confusing? +- **Missing Examples**: What examples would make rules more useful? +- **Template Improvements**: How could investigation templates be better? + +### **Overall Experience** + +- **Time Saved**: How much time did this meta-rule save you? +- **Quality Improvement**: Did following these rules improve your investigation? +- **Recommendation**: Would you recommend this meta-rule to others? + +## Model Implementation Checklist + +### Before Bug Investigation + +- [ ] **Problem Definition**: Clearly define what needs to be investigated +- [ ] **Scope Definition**: Determine investigation scope and boundaries +- [ ] **Evidence Planning**: Plan evidence collection strategy +- [ ] **Stakeholder Identification**: Identify who needs to be involved + +### During Bug Investigation + +- [ ] **Rule Application**: Apply bundled rules in recommended sequence +- [ ] **Evidence Collection**: Collect evidence systematically with timestamps +- [ ] **Documentation**: Document investigation process and findings +- [ ] **Validation**: Verify findings with reproduction steps + +### After Bug Investigation + +- [ ] **Report Creation**: Create comprehensive investigation report +- [ ] **Root Cause Analysis**: Document root cause with evidence +- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness +- [ ] **Process Improvement**: Identify improvements for future investigations + +--- + +**See also**: + +- `.cursor/rules/meta_feature_planning.mdc` for planning investigation work +- `.cursor/rules/meta_bug_fixing.mdc` for implementing fixes +- `.cursor/rules/meta_feature_implementation.mdc` for preventive measures + +**Status**: Active meta-rule for bug diagnosis +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, QA team, DevOps team diff --git a/.cursor/rules/meta_bug_fixing.mdc b/.cursor/rules/meta_bug_fixing.mdc new file mode 100644 index 00000000..d1c2a5d1 --- /dev/null +++ b/.cursor/rules/meta_bug_fixing.mdc @@ -0,0 +1,175 @@ +# Meta-Rule: Bug Fixing + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Bug fix implementation workflow bundling + +## Purpose + +This meta-rule bundles all the rules needed for implementing bug fixes +with proper testing and validation. Use this after diagnosis when +implementing the actual fix. + +## When to Use + +- **Post-Diagnosis**: After root cause is identified and fix is planned +- **Fix Implementation**: When coding the actual bug fix +- **Testing & Validation**: When testing the fix works correctly +- **Code Review**: When reviewing the fix implementation +- **Deployment**: When preparing the fix for deployment +- **Documentation**: When documenting the fix and lessons learned + +## Bundled Rules + +### **Implementation Standards** + +- **`development/software_development.mdc`** - Core development + principles, evidence requirements, and testing strategy +- **`development/type_safety_guide.mdc`** - Type-safe implementation + with proper error handling and type guards +- **`development/logging_migration.mdc`** - Proper logging + implementation and migration from console.* calls + +### **Code Quality & Review** + +- **`development/historical_comment_management.mdc`** - Code quality + standards and comment transformation rules +- **`development/historical_comment_patterns.mdc`** - Specific + patterns for transforming historical comments +- **`development/complexity_assessment.mdc`** - Complexity evaluation + for fix implementation + +### **Platform & Testing** + +- **`app/timesafari_development.mdc`** - TimeSafari-specific + development workflow and testing requirements +- **`app/timesafari_platforms.mdc`** - Platform-specific testing + and validation requirements +- **`architecture/build_validation.mdc`** - Build system validation + and testing procedures + +## Workflow Sequence + +### **Phase 1: Fix Implementation (Start Here)** + +1. **Development Standards** - Apply `software_development.mdc` for + core implementation principles +2. **Type Safety** - Use `type_safety_guide.mdc` for type-safe + implementation +3. **Logging Implementation** - Apply `logging_migration.mdc` for + proper logging + +### **Phase 2: Quality & Review** + +1. **Code Quality** - Use `historical_comment_management.mdc` for + code quality standards +2. **Complexity Assessment** - Apply `complexity_assessment.mdc` to + evaluate fix complexity +3. **Code Review** - Follow review standards from bundled rules + +### **Phase 3: Testing & Validation** + +1. **Platform Testing** - Use `timesafari_platforms.mdc` for + platform-specific testing +2. **Build Validation** - Apply `build_validation.mdc` for build + system compliance +3. **Final Validation** - Verify fix works across all platforms + +## Success Criteria + +- [ ] **Fix implemented** following development standards +- [ ] **Type safety maintained** with proper error handling +- [ ] **Logging properly implemented** with component context +- [ ] **Code quality standards met** with clean, maintainable code +- [ ] **Testing completed** across all target platforms +- [ ] **Build validation passed** with no build system issues +- [ ] **Code review completed** with all feedback addressed +- [ ] **Documentation updated** with fix details and lessons learned + +## Common Pitfalls + +- **Don't skip type safety** - leads to runtime errors +- **Don't ignore logging** - makes future debugging harder +- **Don't skip platform testing** - misses platform-specific issues +- **Don't ignore code quality** - creates technical debt +- **Don't skip build validation** - can break build system +- **Don't forget documentation** - loses fix context for future + +## Integration Points + +### **With Other Meta-Rules** + +- **Bug Diagnosis**: Investigation results drive fix implementation +- **Feature Implementation**: Fix patterns inform future development +- **Feature Planning**: Fix complexity informs future planning + +### **With Development Workflow** + +- Fix implementation follows development standards +- Testing strategy ensures fix quality +- Code review maintains code quality + +## Feedback & Improvement + +### **Sub-Rule Ratings (1-5 scale)** + +- **Development Standards**: ___/5 - Comments: _______________ +- **Type Safety**: ___/5 - Comments: _______________ +- **Logging Migration**: ___/5 - Comments: _______________ +- **Code Quality**: ___/5 - Comments: _______________ +- **Platform Testing**: ___/5 - Comments: _______________ + +### **Workflow Feedback** + +- **Implementation Clarity**: How clear was the implementation guidance? +- **Testing Coverage**: Were testing requirements sufficient or excessive? +- **Process Effectiveness**: How well did the workflow work for you? + +### **Sub-Rule Improvements** + +- **Clarity Issues**: Which rules were unclear or confusing? +- **Missing Examples**: What examples would make rules more useful? +- **Integration Problems**: Do any rules conflict or overlap? + +### **Overall Experience** + +- **Time Saved**: How much time did this meta-rule save you? +- **Quality Improvement**: Did following these rules improve your fix? +- **Recommendation**: Would you recommend this meta-rule to others? + +## Model Implementation Checklist + +### Before Bug Fixing + +- [ ] **Root Cause Understood**: Confirm root cause is clearly identified +- [ ] **Fix Strategy Planned**: Plan implementation approach and testing +- [ ] **Platform Impact Assessed**: Understand impact across all platforms +- [ ] **Testing Strategy Planned**: Plan testing approach for the fix + +### During Bug Fixing + +- [ ] **Rule Application**: Apply bundled rules in recommended sequence +- [ ] **Implementation**: Implement fix following development standards +- [ ] **Testing**: Test fix across all target platforms +- [ ] **Documentation**: Document implementation details and decisions + +### After Bug Fixing + +- [ ] **Validation**: Verify fix meets all success criteria +- [ ] **Code Review**: Complete code review with team +- [ ] **Deployment**: Deploy fix following deployment procedures +- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness + +--- + +**See also**: + +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflow +- `.cursor/rules/meta_feature_implementation.mdc` for implementation patterns +- `.cursor/rules/meta_feature_planning.mdc` for planning future work + +**Status**: Active meta-rule for bug fixing +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, QA team, DevOps team diff --git a/.cursor/rules/meta_core_always_on.mdc b/.cursor/rules/meta_core_always_on.mdc new file mode 100644 index 00000000..6824f5a7 --- /dev/null +++ b/.cursor/rules/meta_core_always_on.mdc @@ -0,0 +1,196 @@ +--- +alwaysApply: true +--- + +# Meta-Rule: Core Always-On Rules + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Core rules for every prompt + +## Purpose + +This meta-rule bundles the core rules that should be applied to **every single +prompt** because they define fundamental behaviors, principles, and context +that are essential for all AI interactions. + +## When to Use + +**ALWAYS** - These rules apply to every single prompt, regardless of the task +or context. They form the foundation for all AI assistant behavior. + +## Bundled Rules + +### **Core Human Competence Principles** + +- **`core/base_context.mdc`** - Human competence first principles, interaction + guidelines, and output contract requirements +- **`core/less_complex.mdc`** - Minimalist solution principle and complexity + guidelines + +### **Time & Context Standards** + +- **`development/time.mdc`** - Time handling principles and UTC standards +- **`development/time_examples.mdc`** - Practical time implementation examples +- **`development/time_implementation.mdc`** - Detailed time implementation + guidelines + +### **Version Control & Process** + +- **`workflow/version_control.mdc`** - Version control principles and commit + guidelines +- **`workflow/commit_messages.mdc`** - Commit message format and conventions + +### **Application Context** + +- **`app/timesafari.mdc`** - Core TimeSafari application context and + development principles +- **`app/timesafari_development.mdc`** - TimeSafari-specific development + workflow and quality standards + +## Why These Rules Are Always-On + +### **Base Context** + +- **Human Competence First**: Every interaction must increase human competence +- **Output Contract**: All responses must follow the required structure +- **Competence Hooks**: Learning and collaboration must be built into every response + +### **Time Standards** + +- **UTC Consistency**: All timestamps must use UTC for system operations +- **Evidence Collection**: Time context is essential for debugging and investigation +- **Cross-Platform**: Time handling affects all platforms and features + +### **Version Control** + +- **Commit Standards**: Every code change must follow commit message conventions +- **Process Consistency**: Version control affects all development work +- **Team Collaboration**: Commit standards enable effective team communication + +### **Application Context** + +- **Platform Awareness**: Every task must consider web/mobile/desktop platforms +- **Architecture Principles**: All work must follow TimeSafari patterns +- **Development Standards**: Quality and testing requirements apply to all work + +## Application Priority + +### **Primary (Apply First)** + +1. **Base Context** - Human competence and output contract +2. **Time Standards** - UTC and timestamp requirements +3. **Application Context** - TimeSafari principles and platforms + +### **Secondary (Apply as Needed)** + +1. **Version Control** - When making code changes +2. **Complexity Guidelines** - When evaluating solution approaches + +## Integration with Other Meta-Rules + +### **Feature Planning** + +- Base context ensures human competence focus +- Time standards inform planning and estimation +- Application context drives platform considerations + +### **Bug Diagnosis** + +- Base context ensures systematic investigation +- Time standards enable proper evidence collection +- Application context provides system understanding + +### **Bug Fixing** + +- Base context ensures quality implementation +- Time standards maintain logging consistency +- Application context guides testing strategy + +### **Feature Implementation** + +- Base context ensures proper development approach +- Time standards maintain system consistency +- Application context drives architecture decisions + +## Success Criteria + +- [ ] **Base context applied** to every single prompt +- [ ] **Time standards followed** for all timestamps and logging +- [ ] **Version control standards** applied to all code changes +- [ ] **Application context considered** for all platform work +- [ ] **Human competence focus** maintained in all interactions +- [ ] **Output contract structure** followed in all responses + +## Common Pitfalls + +- **Don't skip base context** - loses human competence focus +- **Don't ignore time standards** - creates inconsistent timestamps +- **Don't forget application context** - misses platform considerations +- **Don't skip version control** - creates inconsistent commit history +- **Don't lose competence focus** - reduces learning value + +## Feedback & Improvement + +### **Rule Effectiveness Ratings (1-5 scale)** + +- **Base Context**: ___/5 - Comments: _______________ +- **Time Standards**: ___/5 - Comments: _______________ +- **Version Control**: ___/5 - Comments: _______________ +- **Application Context**: ___/5 - Comments: _______________ + +### **Always-On Effectiveness** + +- **Consistency**: Are these rules applied consistently across all prompts? +- **Value**: Do these rules add value to every interaction? +- **Overhead**: Are these rules too burdensome for simple tasks? + +### **Integration Feedback** + +- **With Other Meta-Rules**: How well do these integrate with workflow rules? +- **Context Switching**: Do these rules help or hinder context switching? +- **Learning Curve**: Are these rules easy for new users to understand? + +### **Overall Experience** + +- **Quality Improvement**: Do these rules improve response quality? +- **Efficiency**: Do these rules make interactions more efficient? +- **Recommendation**: Would you recommend keeping these always-on? + +## Model Implementation Checklist + +### Before Every Prompt + +- [ ] **Base Context**: Ensure human competence principles are active +- [ ] **Time Standards**: Verify UTC and timestamp requirements are clear +- [ ] **Application Context**: Confirm TimeSafari context is loaded +- [ ] **Version Control**: Prepare commit standards if code changes are needed + +### During Response Creation + +- [ ] **Output Contract**: Follow required response structure +- [ ] **Competence Hooks**: Include learning and collaboration elements +- [ ] **Time Consistency**: Apply UTC standards for all time references +- [ ] **Platform Awareness**: Consider all target platforms + +### After Response Creation + +- [ ] **Validation**: Verify all always-on rules were applied +- [ ] **Quality Check**: Ensure response meets competence standards +- [ ] **Context Review**: Confirm application context was properly considered +- [ ] **Feedback Collection**: Note any issues with always-on application + +--- + +**See also**: + +- `.cursor/rules/meta_feature_planning.mdc` for workflow-specific rules +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflows +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation +- `.cursor/rules/meta_feature_implementation.mdc` for feature development + +**Status**: Active core always-on meta-rule +**Priority**: Critical (applies to every prompt) +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: All AI interactions, Development team diff --git a/.cursor/rules/meta_feature_implementation.mdc b/.cursor/rules/meta_feature_implementation.mdc new file mode 100644 index 00000000..a24a25fa --- /dev/null +++ b/.cursor/rules/meta_feature_implementation.mdc @@ -0,0 +1,187 @@ +# Meta-Rule: Feature Implementation + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Feature implementation workflow bundling + +## Purpose + +This meta-rule bundles all the rules needed for building features with +proper architecture and cross-platform support. Use this when implementing +planned features or refactoring existing code. + +## When to Use + +- **Feature Development**: Building new features from planning +- **Code Refactoring**: Restructuring existing code for better architecture +- **Platform Expansion**: Adding features to new platforms +- **Service Implementation**: Building new services or components +- **Integration Work**: Connecting features with existing systems +- **Performance Optimization**: Improving feature performance + +## Bundled Rules + +### **Development Foundation** + +- **`app/timesafari_development.mdc`** - TimeSafari-specific + development workflow and quality standards +- **`development/software_development.mdc`** - Core development + principles and evidence requirements +- **`development/type_safety_guide.mdc`** - Type-safe implementation + with proper error handling + +### **Architecture & Patterns** + +- **`app/architectural_patterns.mdc`** - Design patterns and + architectural examples for features +- **`app/architectural_examples.mdc`** - Implementation examples + and testing strategies +- **`app/architectural_implementation.mdc`** - Implementation + guidelines and best practices + +### **Platform & Services** + +- **`app/timesafari_platforms.mdc`** - Platform abstraction + patterns and platform-specific requirements +- **`development/asset_configuration.mdc`** - Asset management + and build integration +- **`development/logging_standards.mdc`** - Proper logging + implementation standards + +### **Quality & Validation** + +- **`architecture/build_validation.mdc`** - Build system + validation and testing procedures +- **`architecture/build_testing.mdc`** - Testing requirements + and feedback collection +- **`development/complexity_assessment.mdc`** - Complexity + evaluation for implementation + +## Workflow Sequence + +### **Phase 1: Implementation Foundation (Start Here)** + +1. **Development Workflow** - Use `timesafari_development.mdc` for + development standards and workflow +2. **Type Safety** - Apply `type_safety_guide.mdc` for type-safe + implementation +3. **Architecture Patterns** - Use `architectural_patterns.mdc` for + design patterns + +### **Phase 2: Feature Development** + +1. **Platform Services** - Apply `timesafari_platforms.mdc` for + platform abstraction +2. **Implementation Examples** - Use `architectural_examples.mdc` + for implementation guidance +3. **Asset Configuration** - Apply `asset_configuration.mdc` for + asset management + +### **Phase 3: Quality & Testing** + +1. **Logging Implementation** - Use `logging_standards.mdc` for + proper logging +2. **Build Validation** - Apply `build_validation.mdc` for build + system compliance +3. **Testing & Feedback** - Use `build_testing.mdc` for testing + requirements + +## Success Criteria + +- [ ] **Feature implemented** following development standards +- [ ] **Type safety maintained** with proper error handling +- [ ] **Architecture patterns applied** consistently +- [ ] **Platform abstraction implemented** correctly +- [ ] **Logging properly implemented** with component context +- [ ] **Assets configured** and integrated with build system +- [ ] **Build validation passed** with no build system issues +- [ ] **Testing completed** across all target platforms +- [ ] **Code review completed** with all feedback addressed + +## Common Pitfalls + +- **Don't skip architecture patterns** - leads to inconsistent design +- **Don't ignore platform abstraction** - creates platform-specific code +- **Don't skip type safety** - leads to runtime errors +- **Don't ignore logging** - makes future debugging harder +- **Don't skip build validation** - can break build system +- **Don't forget asset configuration** - leads to missing assets + +## Integration Points + +### **With Other Meta-Rules** + +- **Feature Planning**: Planning outputs drive implementation approach +- **Bug Fixing**: Implementation patterns inform fix strategies +- **Bug Diagnosis**: Implementation insights help with investigation + +### **With Development Workflow** + +- Implementation follows development standards +- Architecture decisions drive implementation approach +- Platform requirements inform testing strategy + +## Feedback & Improvement + +### **Sub-Rule Ratings (1-5 scale)** + +- **Development Workflow**: ___/5 - Comments: _______________ +- **Type Safety**: ___/5 - Comments: _______________ +- **Architecture Patterns**: ___/5 - Comments: _______________ +- **Platform Services**: ___/5 - Comments: _______________ +- **Build Validation**: ___/5 - Comments: _______________ + +### **Workflow Feedback** + +- **Implementation Clarity**: How clear was the implementation guidance? +- **Pattern Effectiveness**: How well did architecture patterns work? +- **Platform Coverage**: How well did platform guidance cover your needs? + +### **Sub-Rule Improvements** + +- **Clarity Issues**: Which rules were unclear or confusing? +- **Missing Examples**: What examples would make rules more useful? +- **Integration Problems**: Do any rules conflict or overlap? + +### **Overall Experience** + +- **Time Saved**: How much time did this meta-rule save you? +- **Quality Improvement**: Did following these rules improve your implementation? +- **Recommendation**: Would you recommend this meta-rule to others? + +## Model Implementation Checklist + +### Before Feature Implementation + +- [ ] **Planning Review**: Review feature planning and requirements +- [ ] **Architecture Planning**: Plan architecture and design patterns +- [ ] **Platform Analysis**: Understand platform-specific requirements +- [ ] **Testing Strategy**: Plan testing approach for the feature + +### During Feature Implementation + +- [ ] **Rule Application**: Apply bundled rules in recommended sequence +- [ ] **Implementation**: Implement feature following development standards +- [ ] **Testing**: Test feature across all target platforms +- [ ] **Documentation**: Document implementation details and decisions + +### After Feature Implementation + +- [ ] **Validation**: Verify feature meets all success criteria +- [ ] **Code Review**: Complete code review with team +- [ ] **Testing**: Complete comprehensive testing across platforms +- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness + +--- + +**See also**: + +- `.cursor/rules/meta_feature_planning.mdc` for planning workflow +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation patterns +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation insights + +**Status**: Active meta-rule for feature implementation +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, Architecture team, QA team diff --git a/.cursor/rules/meta_feature_planning.mdc b/.cursor/rules/meta_feature_planning.mdc new file mode 100644 index 00000000..6bcd2a2e --- /dev/null +++ b/.cursor/rules/meta_feature_planning.mdc @@ -0,0 +1,165 @@ +# Meta-Rule: Feature Planning + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Feature planning workflow bundling + +## Purpose + +This meta-rule bundles all the rules needed for comprehensive feature planning +across all platforms. Use this when starting any new feature development, +planning sprints, or estimating work effort. + +## When to Use + +- **New Feature Development**: Planning features from concept to implementation +- **Sprint Planning**: Estimating effort and breaking down work +- **Architecture Decisions**: Planning major architectural changes +- **Platform Expansion**: Adding features to new platforms +- **Refactoring Planning**: Planning significant code restructuring + +## Bundled Rules + +### **Core Planning Foundation** + +- **`development/planning_examples.mdc`** - Planning templates, examples, and + best practices for structured planning +- **`development/realistic_time_estimation.mdc`** - Time estimation framework + with complexity-based phases and milestones +- **`development/complexity_assessment.mdc`** - Technical and business + complexity evaluation with risk assessment + +### **Platform & Architecture** + +- **`app/timesafari_platforms.mdc`** - Platform-specific requirements, + constraints, and capabilities across web/mobile/desktop +- **`app/architectural_decision_record.mdc`** - ADR process for documenting + major architectural decisions and trade-offs + +### **Development Context** + +- **`app/timesafari.mdc`** - Core application context, principles, and + development focus areas +- **`app/timesafari_development.mdc`** - TimeSafari-specific development + workflow and quality standards + +## Workflow Sequence + +### **Phase 1: Foundation (Start Here)** + +1. **Complexity Assessment** - Use `complexity_assessment.mdc` to evaluate + technical and business complexity +2. **Time Estimation** - Apply `realistic_time_estimation.mdc` framework + based on complexity results +3. **Core Planning** - Use `planning_examples.mdc` for structured planning + approach + +### **Phase 2: Platform & Architecture** + +1. **Platform Analysis** - Review `timesafari_platforms.mdc` for + platform-specific requirements +2. **Architecture Planning** - Use `architectural_decision_record.mdc` if + major architectural changes are needed + +### **Phase 3: Implementation Planning** + +1. **Development Workflow** - Reference `timesafari_development.mdc` for + development standards and testing strategy +2. **Final Planning** - Consolidate all inputs into comprehensive plan + +## Success Criteria + +- [ ] **Complexity assessed** and documented with risk factors +- [ ] **Time estimate created** with clear phases and milestones +- [ ] **Platform requirements identified** for all target platforms +- [ ] **Architecture decisions documented** (if major changes needed) +- [ ] **Testing strategy planned** with platform-specific considerations +- [ ] **Dependencies mapped** between tasks and phases +- [ ] **Stakeholder input gathered** and incorporated + +## Common Pitfalls + +- **Don't skip complexity assessment** - leads to unrealistic estimates +- **Don't estimate without platform analysis** - misses platform-specific work +- **Don't plan without stakeholder input** - creates misaligned expectations +- **Don't ignore testing strategy** - leads to incomplete planning +- **Don't skip architecture decisions** - creates technical debt + +## Integration Points + +### **With Other Meta-Rules** + +- **Bug Diagnosis**: Use complexity assessment for bug investigation planning +- **Feature Implementation**: This planning feeds directly into implementation +- **Code Review**: Planning standards inform review requirements + +### **With Development Workflow** + +- Planning outputs become inputs for sprint planning +- Complexity assessment informs testing strategy +- Platform requirements drive architecture decisions + +## Feedback & Improvement + +### **Sub-Rule Ratings (1-5 scale)** + +- **Complexity Assessment**: ___/5 - Comments: _______________ +- **Time Estimation**: ___/5 - Comments: _______________ +- **Planning Examples**: ___/5 - Comments: _______________ +- **Platform Analysis**: ___/5 - Comments: _______________ +- **Architecture Decisions**: ___/5 - Comments: _______________ + +### **Workflow Feedback** + +- **Sequence Effectiveness**: Did the recommended order work for you? +- **Missing Guidance**: What additional information would have helped? +- **Process Gaps**: Where did the workflow break down? + +### **Sub-Rule Improvements** + +- **Clarity Issues**: Which rules were unclear or confusing? +- **Missing Examples**: What examples would make rules more useful? +- **Integration Problems**: Do any rules conflict or overlap? + +### **Overall Experience** + +- **Time Saved**: How much time did this meta-rule save you? +- **Quality Improvement**: Did following these rules improve your planning? +- **Recommendation**: Would you recommend this meta-rule to others? + +## Model Implementation Checklist + +### Before Feature Planning + +- [ ] **Scope Definition**: Clearly define the feature scope and boundaries +- [ ] **Stakeholder Identification**: Identify all stakeholders and decision makers +- [ ] **Platform Requirements**: Understand target platforms and constraints +- [ ] **Complexity Assessment**: Plan complexity evaluation approach + +### During Feature Planning + +- [ ] **Rule Application**: Apply bundled rules in recommended sequence +- [ ] **Documentation**: Document all planning decisions and rationale +- [ ] **Stakeholder Input**: Gather and incorporate stakeholder feedback +- [ ] **Validation**: Validate planning against success criteria + +### After Feature Planning + +- [ ] **Plan Review**: Review plan with stakeholders and team +- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness +- [ ] **Documentation Update**: Update relevant documentation +- [ ] **Process Improvement**: Identify improvements for future planning + +--- + +**See also**: + +- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation planning +- `.cursor/rules/meta_feature_implementation.mdc` for implementation workflow +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation + +**Status**: Active meta-rule for feature planning +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, Product team, Architecture team diff --git a/.cursor/rules/meta_research.mdc b/.cursor/rules/meta_research.mdc new file mode 100644 index 00000000..2e7d3175 --- /dev/null +++ b/.cursor/rules/meta_research.mdc @@ -0,0 +1,247 @@ +# Meta-Rule: Enhanced Research Workflows + +**Author**: Matthew Raymer +**Date**: 2025-01-27 +**Status**: 🎯 **ACTIVE** - Research and investigation workflows + +## Purpose + +This meta-rule bundles research-specific rules that should be applied when conducting +systematic investigation, analysis, evidence collection, or research tasks. It provides +a comprehensive framework for thorough, methodical research workflows that produce +actionable insights and evidence-based conclusions. + +## When to Use + +**RESEARCH TASKS** - Apply this meta-rule when: + +- Investigating bugs, defects, or system issues +- Conducting technical research or feasibility analysis +- Analyzing codebases, architectures, or dependencies +- Researching solutions, alternatives, or best practices +- Collecting evidence for decision-making or documentation +- Performing root cause analysis or impact assessment + +## Bundled Rules + +### **Core Research Principles** + +- **`development/research_diagnostic.mdc`** - Systematic investigation workflow + and evidence collection methodology +- **`development/type_safety_guide.mdc`** - Type analysis and safety research + for TypeScript/JavaScript codebases + +### **Investigation & Analysis** + +- **`workflow/version_control.mdc`** - Git history analysis and commit research +- **`workflow/commit_messages.mdc`** - Commit pattern analysis and history + investigation + +### **Platform & Context Research** + +- **`app/timesafari.mdc`** - Application context research and platform + understanding +- **`app/timesafari_platforms.mdc`** - Platform-specific research and + capability analysis + +## Why These Rules Are Research-Focused + +### **Research Diagnostic** + +- **Systematic Approach**: Provides structured investigation methodology +- **Evidence Collection**: Ensures thorough data gathering and documentation +- **Root Cause Analysis**: Guides systematic problem investigation +- **Impact Assessment**: Helps evaluate scope and consequences + +### **Type Safety Research** + +- **Code Analysis**: Enables systematic type system investigation +- **Safety Assessment**: Guides research into type-related issues +- **Migration Planning**: Supports research for architectural changes + +### **Version Control Research** + +- **History Analysis**: Enables investigation of code evolution +- **Pattern Recognition**: Helps identify commit and change patterns +- **Timeline Research**: Supports chronological investigation + +### **Platform Research** + +- **Capability Analysis**: Guides research into platform-specific features +- **Context Understanding**: Ensures research considers application context +- **Cross-Platform Research**: Supports multi-platform investigation + +## Application Priority + +### **Primary (Apply First)** + +1. **Research Diagnostic** - Systematic investigation methodology +2. **Type Safety Guide** - Code analysis and type research +3. **Application Context** - Platform and context understanding + +### **Secondary (Apply as Needed)** + +1. **Version Control** - When investigating code history +2. **Platform Details** - When researching platform-specific capabilities + +## Integration with Other Meta-Rules + +### **Bug Diagnosis** + +- Research meta-rule provides investigation methodology +- Core always-on ensures systematic approach +- Application context provides system understanding + +### **Feature Planning** + +- Research meta-rule guides feasibility research +- Core always-on ensures competence focus +- Application context drives platform considerations + +### **Architecture Analysis** + +- Research meta-rule provides systematic analysis framework +- Core always-on ensures quality standards +- Application context informs architectural decisions + +### **Performance Investigation** + +- Research meta-rule guides systematic performance research +- Core always-on ensures thorough investigation +- Application context provides performance context + +## Research Workflow Phases + +### **Phase 1: Investigation Setup** + +1. **Scope Definition** - Define research boundaries and objectives +2. **Context Gathering** - Collect relevant application and platform context +3. **Methodology Selection** - Choose appropriate research approaches + +### **Phase 2: Evidence Collection** + +1. **Systematic Data Gathering** - Collect evidence using structured methods +2. **Documentation** - Record all findings and observations +3. **Validation** - Verify evidence accuracy and relevance + +### **Phase 3: Analysis & Synthesis** + +1. **Pattern Recognition** - Identify trends and patterns in evidence +2. **Root Cause Analysis** - Determine underlying causes and factors +3. **Impact Assessment** - Evaluate scope and consequences + +### **Phase 4: Conclusion & Action** + +1. **Evidence-Based Conclusions** - Draw conclusions from collected evidence +2. **Actionable Recommendations** - Provide specific, implementable guidance +3. **Documentation** - Create comprehensive research documentation + +## Success Criteria + +- [ ] **Research diagnostic applied** to all investigation tasks +- [ ] **Type safety research** conducted for code analysis +- [ ] **Evidence collection** systematic and comprehensive +- [ ] **Root cause analysis** thorough and accurate +- [ ] **Conclusions actionable** and evidence-based +- [ ] **Documentation complete** and searchable + +## Common Research Pitfalls + +- **Don't skip systematic approach** - leads to incomplete investigation +- **Don't ignore evidence validation** - creates unreliable conclusions +- **Don't forget context** - misses important factors +- **Don't skip documentation** - loses research value +- **Don't rush conclusions** - produces poor recommendations + +## Research Quality Standards + +### **Evidence Quality** + +- **Completeness**: All relevant evidence collected +- **Accuracy**: Evidence verified and validated +- **Relevance**: Evidence directly addresses research questions +- **Timeliness**: Evidence current and up-to-date + +### **Analysis Quality** + +- **Systematic**: Analysis follows structured methodology +- **Objective**: Analysis free from bias and assumptions +- **Thorough**: All evidence considered and evaluated +- **Logical**: Conclusions follow from evidence + +### **Documentation Quality** + +- **Comprehensive**: All findings and methods documented +- **Searchable**: Documentation easily findable and navigable +- **Actionable**: Recommendations specific and implementable +- **Maintainable**: Documentation structure supports updates + +## Feedback & Improvement + +### **Rule Effectiveness Ratings (1-5 scale)** + +- **Research Diagnostic**: ___/5 - Comments: _______________ +- **Type Safety Guide**: ___/5 - Comments: _______________ +- **Version Control**: ___/5 - Comments: _______________ +- **Platform Context**: ___/5 - Comments: _______________ + +### **Research Workflow Effectiveness** + +- **Investigation Quality**: Are research tasks producing thorough results? +- **Evidence Collection**: Is evidence gathering systematic and complete? +- **Conclusion Quality**: Are conclusions actionable and evidence-based? +- **Documentation Value**: Is research documentation useful and maintainable? + +### **Integration Feedback** + +- **With Other Meta-Rules**: How well does this integrate with workflow rules? +- **Context Switching**: Do these rules help or hinder research context? +- **Learning Curve**: Are these rules easy for new researchers to understand? + +### **Overall Research Experience** + +- **Quality Improvement**: Do these rules improve research outcomes? +- **Efficiency**: Do these rules make research more efficient? +- **Recommendation**: Would you recommend keeping this research meta-rule? + +## Model Implementation Checklist + +### Before Research Tasks + +- [ ] **Research Diagnostic**: Ensure systematic investigation methodology +- [ ] **Type Safety Guide**: Prepare for code analysis if needed +- [ ] **Application Context**: Load relevant platform and context information +- [ ] **Version Control**: Prepare for history analysis if needed + +### During Research Execution + +- [ ] **Systematic Approach**: Follow structured investigation methodology +- [ ] **Evidence Collection**: Gather comprehensive and validated evidence +- [ ] **Documentation**: Record all findings and observations +- [ ] **Context Awareness**: Consider application and platform context + +### After Research Completion + +- [ ] **Validation**: Verify all research phases completed +- [ ] **Quality Check**: Ensure research meets quality standards +- [ ] **Documentation Review**: Confirm research properly documented +- [ ] **Feedback Collection**: Note any issues with research process + +--- + +**See also**: + +- `.cursor/rules/meta_core_always_on.mdc` for core always-on rules +- `.cursor/rules/meta_feature_planning.mdc` for feature development workflows +- `.cursor/rules/meta_bug_diagnosis.mdc` for bug investigation workflows +- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation workflows + +**Status**: Active research meta-rule +**Priority**: High (applies to all research tasks) +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Development team, Research team, Quality Assurance team +description: +globs: +alwaysApply: false +--- diff --git a/.cursor/rules/meta_rule_architecture.md b/.cursor/rules/meta_rule_architecture.md new file mode 100644 index 00000000..9f0bfb0b --- /dev/null +++ b/.cursor/rules/meta_rule_architecture.md @@ -0,0 +1,103 @@ +# Meta-Rule Architecture Overview + +**Author**: Matthew Raymer +**Date**: 2025-01-27 +**Status**: 📋 **ACTIVE** - Meta-rule organization and relationships + +## Meta-Rule Structure + +### **Core Always-On Rules** (`meta_core_always_on.mdc`) +- **Purpose**: Applied to every single prompt +- **Scope**: Human competence, time standards, version control, application context +- **Priority**: Critical - foundation for all interactions + +### **Enhanced Research Workflows** (`meta_research.mdc`) ⭐ **NEW** +- **Purpose**: Applied to research, investigation, and analysis tasks +- **Scope**: Systematic investigation, evidence collection, root cause analysis +- **Priority**: High - applies to all research tasks +- **Bundles**: Research diagnostic, type safety, version control research, platform context + +### **Feature Development Workflows** (`meta_feature_planning.mdc`) +- **Purpose**: Applied to feature planning and development tasks +- **Scope**: Requirements analysis, architecture planning, implementation strategy +- **Priority**: High - applies to feature development + +### **Bug Investigation Workflows** (`meta_bug_diagnosis.mdc`) +- **Purpose**: Applied to bug investigation and diagnosis tasks +- **Scope**: Defect analysis, evidence collection, root cause identification +- **Priority**: High - applies to bug investigation + +### **Bug Fixing Workflows** (`meta_bug_fixing.mdc`) +- **Purpose**: Applied to bug fixing and resolution tasks +- **Scope**: Fix implementation, testing, validation +- **Priority**: High - applies to bug resolution + +## Research Meta-Rule Integration + +### **When to Use Research Meta-Rule** + +The research meta-rule should be applied when: +- **Investigating bugs** - systematic defect analysis +- **Researching solutions** - feasibility and alternative analysis +- **Analyzing codebases** - architecture and dependency research +- **Collecting evidence** - systematic data gathering +- **Root cause analysis** - systematic problem investigation +- **Impact assessment** - scope and consequence evaluation + +### **How It Complements Other Meta-Rules** + +- **Core Always-On**: Provides foundation (competence, time, context) +- **Research**: Adds systematic investigation methodology +- **Feature Planning**: Guides feasibility research and analysis +- **Bug Diagnosis**: Provides investigation framework +- **Bug Fixing**: Informs fix strategy through research + +### **Research Workflow Phases** + +1. **Investigation Setup** - Scope, context, methodology +2. **Evidence Collection** - Systematic data gathering +3. **Analysis & Synthesis** - Pattern recognition, root cause +4. **Conclusion & Action** - Evidence-based recommendations + +## Usage Examples + +### **Bug Investigation** +``` +Apply: meta_core_always_on + meta_research + meta_bug_diagnosis +Result: Systematic investigation with evidence collection and root cause analysis +``` + +### **Feature Research** +``` +Apply: meta_core_always_on + meta_research + meta_feature_planning +Result: Comprehensive feasibility research with platform context +``` + +### **Architecture Analysis** +``` +Apply: meta_core_always_on + meta_research +Result: Systematic architecture investigation with evidence-based conclusions +``` + +## Benefits of Enhanced Research Meta-Rule + +- **Systematic Approach**: Structured investigation methodology +- **Evidence-Based**: Comprehensive data collection and validation +- **Quality Standards**: Defined research quality criteria +- **Integration**: Seamless integration with existing workflows +- **Documentation**: Comprehensive research documentation standards + +## Next Steps + +1. **Test Research Meta-Rule** - Apply to next research task +2. **Validate Integration** - Ensure smooth workflow integration +3. **Collect Feedback** - Gather effectiveness ratings +4. **Iterate** - Refine based on usage experience + +--- + +**Status**: Active documentation +**Priority**: Medium +**Estimated Effort**: Ongoing reference +**Dependencies**: All meta-rules +**Stakeholders**: Development team, Research team diff --git a/.cursor/rules/realistic_time_estimation.mdc b/.cursor/rules/realistic_time_estimation.mdc deleted file mode 100644 index aa48577a..00000000 --- a/.cursor/rules/realistic_time_estimation.mdc +++ /dev/null @@ -1,348 +0,0 @@ ---- -description: when generating text that has project task work estimates -alwaysApply: false ---- -# No Time Estimates — Harbor Pilot Directive - -> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, milestones, and complexity levels. Time estimates are consistently wrong and create unrealistic expectations. - -## 🎯 Purpose - -Development time estimates are consistently wrong and create unrealistic expectations. This rule ensures we focus on phases, milestones, and complexity rather than trying to predict specific timeframes. - -## 🚨 Critical Rule - -**DO NOT MAKE TIME ESTIMATES** -- **Never provide specific time estimates** - they are always wrong -- **Use phases and milestones** instead of days/weeks -- **Focus on complexity and dependencies** rather than time -- **Set expectations based on progress, not deadlines** - -## 📊 Planning Framework (Not Time Estimates) - -### **Complexity Categories** -- **Simple**: Text changes, styling updates, minor bug fixes -- **Medium**: New features, refactoring, component updates -- **Complex**: Architecture changes, integrations, cross-platform work -- **Unknown**: New technologies, APIs, or approaches - -### **Platform Complexity** -- **Single platform**: Web-only or mobile-only changes -- **Two platforms**: Web + mobile or web + desktop -- **Three platforms**: Web + mobile + desktop -- **Cross-platform consistency**: Ensuring behavior matches across all platforms - -### **Testing Complexity** -- **Basic**: Unit tests for new functionality -- **Comprehensive**: Integration tests, cross-platform testing -- **User acceptance**: User testing, feedback integration - -## 🔍 Planning Process (No Time Estimates) - -### **Step 1: Break Down the Work** -- Identify all subtasks and dependencies -- Group related work into logical phases -- Identify critical path and blockers - -### **Step 2: Define Phases and Milestones** -- **Phase 1**: Foundation work (basic fixes, core functionality) -- **Phase 2**: Enhancement work (new features, integrations) -- **Phase 3**: Polish work (testing, user experience, edge cases) - -### **Step 3: Identify Dependencies** -- **Technical dependencies**: What must be built first -- **Platform dependencies**: What works on which platforms -- **Testing dependencies**: What can be tested when - -### **Step 4: Set Progress Milestones** -- **Milestone 1**: Basic functionality working -- **Milestone 2**: All platforms supported -- **Milestone 3**: Fully tested and polished - -## 📋 Planning Checklist (No Time Estimates) - -- [ ] Work broken down into logical phases -- [ ] Dependencies identified and mapped -- [ ] Milestones defined with clear criteria -- [ ] Complexity levels assigned to each phase -- [ ] Platform requirements identified -- [ ] Testing strategy planned -- [ ] Risk factors identified -- [ ] Success criteria defined - -## 🎯 Example Planning (No Time Estimates) - -### **Example 1: Simple Feature** -``` -Phase 1: Core implementation -- Basic functionality -- Single platform support -- Unit tests - -Phase 2: Platform expansion -- Multi-platform support -- Integration tests - -Phase 3: Polish -- User testing -- Edge case handling -``` - -### **Example 2: Complex Cross-Platform Feature** -``` -Phase 1: Foundation -- Architecture design -- Core service implementation -- Basic web platform support - -Phase 2: Platform Integration -- Mobile platform support -- Desktop platform support -- Cross-platform consistency - -Phase 3: Testing & Polish -- Comprehensive testing -- Error handling -- User experience refinement -``` - -## 🚫 Anti-Patterns to Avoid - -- **"This should take X days"** - Red flag for time estimation -- **"Just a few hours"** - Ignores complexity and testing -- **"Similar to X"** - Without considering differences -- **"Quick fix"** - Nothing is ever quick in software -- **"No testing needed"** - Testing always takes effort - -## ✅ Best Practices - -### **When Planning:** -1. **Break down everything** - no work is too small to plan -2. **Consider all platforms** - web, mobile, desktop differences -3. **Include testing strategy** - unit, integration, and user testing -4. **Account for unknowns** - there are always surprises -5. **Focus on dependencies** - what blocks what - -### **When Presenting Plans:** -1. **Show the phases** - explain the logical progression -2. **Highlight dependencies** - what could block progress -3. **Define milestones** - clear success criteria -4. **Identify risks** - what could go wrong -5. **Suggest alternatives** - ways to reduce scope or complexity - -## 🔄 Continuous Improvement - -### **Track Progress** -- Record planned vs. actual phases completed -- Identify what took longer than expected -- Learn from complexity misjudgments -- Adjust planning process based on experience - -### **Learn from Experience** -- **Underestimated complexity**: Increase complexity categories -- **Missed dependencies**: Improve dependency mapping -- **Platform surprises**: Better platform research upfront - -## 🎯 Integration with Harbor Pilot - -This rule works in conjunction with: -- **Project Planning**: Focuses on phases and milestones -- **Resource Allocation**: Based on complexity, not time -- **Risk Management**: Identifies blockers and dependencies -- **Stakeholder Communication**: Sets progress-based expectations - -## 📝 Version History - -### v2.0.0 (2025-08-21) -- **Major Change**: Completely removed time estimation approach -- **New Focus**: Phases, milestones, and complexity-based planning -- **Eliminated**: All time multipliers, estimates, and calculations -- **Added**: Dependency mapping and progress milestone framework - -### v1.0.0 (2025-08-21) -- Initial creation based on user feedback about estimation accuracy -- ~~Established realistic estimation multipliers and process~~ -- ~~Added comprehensive estimation checklist and examples~~ -- Integrated with Harbor Pilot planning and risk management - ---- - -## 🚨 Remember - -**DO NOT MAKE TIME ESTIMATES. Use phases, milestones, and complexity instead. Focus on progress, not deadlines.** - -## 🚨 Remember - -**Your first estimate is wrong. Your second estimate is probably still wrong. Focus on progress, not deadlines.** -# No Time Estimates — Harbor Pilot Directive - -> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, milestones, and complexity levels. Time estimates are consistently wrong and create unrealistic expectations. - -## 🎯 Purpose - -Development time estimates are consistently wrong and create unrealistic expectations. This rule ensures we focus on phases, milestones, and complexity rather than trying to predict specific timeframes. - -## 🚨 Critical Rule - -**DO NOT MAKE TIME ESTIMATES** -- **Never provide specific time estimates** - they are always wrong -- **Use phases and milestones** instead of days/weeks -- **Focus on complexity and dependencies** rather than time -- **Set expectations based on progress, not deadlines** - -## 📊 Planning Framework (Not Time Estimates) - -### **Complexity Categories** -- **Simple**: Text changes, styling updates, minor bug fixes -- **Medium**: New features, refactoring, component updates -- **Complex**: Architecture changes, integrations, cross-platform work -- **Unknown**: New technologies, APIs, or approaches - -### **Platform Complexity** -- **Single platform**: Web-only or mobile-only changes -- **Two platforms**: Web + mobile or web + desktop -- **Three platforms**: Web + mobile + desktop -- **Cross-platform consistency**: Ensuring behavior matches across all platforms - -### **Testing Complexity** -- **Basic**: Unit tests for new functionality -- **Comprehensive**: Integration tests, cross-platform testing -- **User acceptance**: User testing, feedback integration - -## 🔍 Planning Process (No Time Estimates) - -### **Step 1: Break Down the Work** -- Identify all subtasks and dependencies -- Group related work into logical phases -- Identify critical path and blockers - -### **Step 2: Define Phases and Milestones** -- **Phase 1**: Foundation work (basic fixes, core functionality) -- **Phase 2**: Enhancement work (new features, integrations) -- **Phase 3**: Polish work (testing, user experience, edge cases) - -### **Step 3: Identify Dependencies** -- **Technical dependencies**: What must be built first -- **Platform dependencies**: What works on which platforms -- **Testing dependencies**: What can be tested when - -### **Step 4: Set Progress Milestones** -- **Milestone 1**: Basic functionality working -- **Milestone 2**: All platforms supported -- **Milestone 3**: Fully tested and polished - -## 📋 Planning Checklist (No Time Estimates) - -- [ ] Work broken down into logical phases -- [ ] Dependencies identified and mapped -- [ ] Milestones defined with clear criteria -- [ ] Complexity levels assigned to each phase -- [ ] Platform requirements identified -- [ ] Testing strategy planned -- [ ] Risk factors identified -- [ ] Success criteria defined - -## 🎯 Example Planning (No Time Estimates) - -### **Example 1: Simple Feature** -``` -Phase 1: Core implementation -- Basic functionality -- Single platform support -- Unit tests - -Phase 2: Platform expansion -- Multi-platform support -- Integration tests - -Phase 3: Polish -- User testing -- Edge case handling -``` - -### **Example 2: Complex Cross-Platform Feature** -``` -Phase 1: Foundation -- Architecture design -- Core service implementation -- Basic web platform support - -Phase 2: Platform Integration -- Mobile platform support -- Desktop platform support -- Cross-platform consistency - -Phase 3: Testing & Polish -- Comprehensive testing -- Error handling -- User experience refinement -``` - -## 🚫 Anti-Patterns to Avoid - -- **"This should take X days"** - Red flag for time estimation -- **"Just a few hours"** - Ignores complexity and testing -- **"Similar to X"** - Without considering differences -- **"Quick fix"** - Nothing is ever quick in software -- **"No testing needed"** - Testing always takes effort - -## ✅ Best Practices - -### **When Planning:** -1. **Break down everything** - no work is too small to plan -2. **Consider all platforms** - web, mobile, desktop differences -3. **Include testing strategy** - unit, integration, and user testing -4. **Account for unknowns** - there are always surprises -5. **Focus on dependencies** - what blocks what - -### **When Presenting Plans:** -1. **Show the phases** - explain the logical progression -2. **Highlight dependencies** - what could block progress -3. **Define milestones** - clear success criteria -4. **Identify risks** - what could go wrong -5. **Suggest alternatives** - ways to reduce scope or complexity - -## 🔄 Continuous Improvement - -### **Track Progress** -- Record planned vs. actual phases completed -- Identify what took longer than expected -- Learn from complexity misjudgments -- Adjust planning process based on experience - -### **Learn from Experience** -- **Underestimated complexity**: Increase complexity categories -- **Missed dependencies**: Improve dependency mapping -- **Platform surprises**: Better platform research upfront - -## 🎯 Integration with Harbor Pilot - -This rule works in conjunction with: -- **Project Planning**: Focuses on phases and milestones -- **Resource Allocation**: Based on complexity, not time -- **Risk Management**: Identifies blockers and dependencies -- **Stakeholder Communication**: Sets progress-based expectations - -## 📝 Version History - -### v2.0.0 (2025-08-21) -- **Major Change**: Completely removed time estimation approach -- **New Focus**: Phases, milestones, and complexity-based planning -- **Eliminated**: All time multipliers, estimates, and calculations -- **Added**: Dependency mapping and progress milestone framework - -### v1.0.0 (2025-08-21) -- Initial creation based on user feedback about estimation accuracy -- ~~Established realistic estimation multipliers and process~~ -- ~~Added comprehensive estimation checklist and examples~~ -- Integrated with Harbor Pilot planning and risk management - ---- - -## 🚨 Remember - -**DO NOT MAKE TIME ESTIMATES. Use phases, milestones, and complexity instead. Focus on progress, not deadlines.** - -## 🚨 Remember - -**Your first estimate is wrong. Your second estimate is probably still wrong. Focus on progress, not deadlines.** diff --git a/.cursor/rules/adr_template.mdc b/.cursor/rules/templates/adr_template.mdc similarity index 59% rename from .cursor/rules/adr_template.mdc rename to .cursor/rules/templates/adr_template.mdc index ce75d9ab..6114b287 100644 --- a/.cursor/rules/adr_template.mdc +++ b/.cursor/rules/templates/adr_template.mdc @@ -1,3 +1,7 @@ +--- +alwaysApply: false +--- + # ADR Template ## ADR-XXXX-YY-ZZ: [Short Title] @@ -11,37 +15,47 @@ [Describe the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as -such. The language in this section is value-neutral. It is simply describing facts.] +such. The language in this section is value-neutral. It is simply describing + facts.] ## Decision -[Describe our response to these forces. We will use the past tense ("We will...").] +[Describe our response to these forces. We will use the past tense ( + "We will...").] ## Consequences ### Positive + - [List positive consequences] ### Negative + - [List negative consequences or trade-offs] ### Neutral + - [List neutral consequences or notes] ## Alternatives Considered - **Alternative 1:** [Description] - [Why rejected] + - **Alternative 2:** [Description] - [Why rejected] + - **Alternative 3:** [Description] - [Why rejected] ## Implementation Notes -[Any specific implementation details, migration steps, or technical considerations] +[Any specific implementation details, migration steps, or + technical considerations] ## References - [Link to relevant documentation] + - [Link to related ADRs] + - [Link to external resources] ## Related Decisions @@ -59,7 +73,26 @@ such. The language in this section is value-neutral. It is simply describing fac 5. **Link to related issues** and documentation 6. **Update status** as decisions evolve 7. **Store in** `doc/architecture-decisions/` directory -description: -globs: -alwaysApply: false ---- + +## Model Implementation Checklist + +### Before ADR Creation + +- [ ] **Decision Context**: Understand the decision that needs to be made +- [ ] **Stakeholder Identification**: Identify all decision makers +- [ ] **Research**: Research alternatives and gather evidence +- [ ] **Template Selection**: Choose appropriate ADR template + +### During ADR Creation + +- [ ] **Context Documentation**: Document the context and forces at play +- [ ] **Decision Recording**: Record the decision and rationale +- [ ] **Consequences Analysis**: Analyze positive, negative, and neutral consequences +- [ ] **Alternatives Documentation**: Document alternatives considered + +### After ADR Creation + +- [ ] **Review**: Review ADR with stakeholders +- [ ] **Approval**: Get approval from decision makers +- [ ] **Communication**: Communicate decision to team +- [ ] **Implementation**: Plan implementation of the decision diff --git a/.cursor/rules/workflow/commit_messages.mdc b/.cursor/rules/workflow/commit_messages.mdc new file mode 100644 index 00000000..7ecebfd6 --- /dev/null +++ b/.cursor/rules/workflow/commit_messages.mdc @@ -0,0 +1,196 @@ +# Commit Message Format and Templates + +> **Agent role**: + Reference this file for commit message formatting and templates. + +## Commit Message Format (Normative) + +### A. Subject Line (required) + +``` + +<type>(<scope>)<!>: <summary> + +``` + +- **type** (lowercase, Conventional Commits): + + `feat|fix|refactor|perf|docs|test|build|chore|ci|revert` + +- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`) + +- **!**: include when a breaking change is introduced + +- **summary**: imperative mood, ≤ 72 chars, no trailing period + +**Examples** + +- `fix(api): handle null token in refresh path` + +- `feat(ui/login)!: require OTP after 3 failed attempts` + +### B. Body (optional, when it adds non-obvious value) + +- One blank line after subject. + +- Wrap at ~72 chars. + +- Explain **what** and **why**, not line-by-line "how". + +- Include brief notes like tests passing or TS/lint issues resolved + + **only if material**. + +**Body checklist** + +- [ ] Problem/symptom being addressed + +- [ ] High-level approach or rationale + +- [ ] Risks, tradeoffs, or follow-ups (if any) + +### C. Footer (optional) + +- Issue refs: `Closes #123`, `Refs #456` + +- Breaking change (alternative to `!`): + + `BREAKING CHANGE: <impact + migration note>` + +- Authors: `Co-authored-by: Name <email>` + +- Security: `CVE-XXXX-YYYY: <short note>` (if applicable) + +## Content Guidance + +### Include (when relevant) + +- Specific fixes/features delivered + +- Symptoms/problems fixed + +- Brief note that tests passed or TS/lint errors resolved + +### Avoid + +- Vague: *improved, enhanced, better* + +- Trivialities: tiny docs, one-liners, pure lint cleanups (separate, + + focused commits if needed) + +- Redundancy: generic blurbs repeated across files + +- Multi-purpose dumps: keep commits **narrow and focused** + +- Long explanations that good inline code comments already cover + +**Guiding Principle:** Let code and inline docs speak. Use commits to +highlight what isn't obvious. + +## Copy-Paste Templates + +### Minimal (no body) + +```text + +<type>(<scope>): <summary> + +``` + +### Standard (with body & footer) + +```text + +<type>(<scope>)<!>: <summary> + +<why-this-change?> +<what-it-does?> +<risks-or-follow-ups?> + +Closes #<id> +BREAKING CHANGE: <impact + migration> +Co-authored-by: <Name> <email> + +``` + +## Type Descriptions + +### feat + +New feature for the user + +### fix + +Bug fix for the user + +### docs + +Documentation only changes + +### style + +Changes that do not affect the meaning of the code + +### refactor + +Code change that neither fixes a bug nor adds a feature + +### perf + +Code change that improves performance + +### test + +Adding missing tests or correcting existing tests + +### build + +Changes that affect the build system or external dependencies + +### ci + +Changes to CI configuration files and scripts + +### chore + +Other changes that don't modify src or test files + +--- + +**See also**: + +- `.cursor/rules/workflow/version_control.mdc` for + + core version control principles + +- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details + +**Status**: Active commit message guidelines +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: version_control.mdc +**Stakeholders**: Development team, AI assistants + +## Model Implementation Checklist + +### Before Creating Commits + +- [ ] **Change Review**: Review all changes to be committed +- [ ] **Scope Assessment**: Determine if changes belong in single or multiple commits +- [ ] **Message Planning**: Plan clear, descriptive commit message +- [ ] **Convention Check**: Review commit message format requirements + +### During Commit Creation + +- [ ] **Type Selection**: Choose appropriate commit type (feat, fix, docs, etc.) +- [ ] **Message Writing**: Write clear, concise commit message +- [ ] **Body Content**: Add detailed description if needed +- [ ] **Breaking Changes**: Document breaking changes with `!` and migration notes + +### After Commit Creation + +- [ ] **Message Review**: Verify commit message follows conventions +- [ ] **Change Validation**: Confirm all intended changes are included +- [ ] **Documentation**: Update any related documentation +- [ ] **Team Communication**: Communicate significant changes to team diff --git a/.cursor/rules/workflow/version_control.mdc b/.cursor/rules/workflow/version_control.mdc index 6e619f5c..d501c162 100644 --- a/.cursor/rules/workflow/version_control.mdc +++ b/.cursor/rules/workflow/version_control.mdc @@ -1,155 +1,41 @@ ---- -description: interacting with git -alwaysApply: false ---- # Directive: Peaceful Co-Existence with Developers **Author**: Matthew Raymer **Date**: 2025-08-19 **Status**: 🎯 **ACTIVE** - Version control guidelines -## 1) Version-Control Ownership +## Core Principles + +### 1) Version-Control Ownership - **MUST NOT** run `git add`, `git commit`, or any write action. - **MUST** leave staging/committing to the developer. -## 2) Source of Truth for Commit Text +### 2) Source of Truth for Commit Text - **MUST** derive messages **only** from: + - files **staged** for commit (primary), and - files **awaiting staging** (context). + - **MUST** use the **diffs** to inform content. - **MUST NOT** invent changes or imply work not present in diffs. -## 3) Mandatory Preview Flow +### 3) Mandatory Preview Flow - **ALWAYS** present, before any real commit: + - file list + brief per-file notes, - a **draft commit message** (copy-paste ready), - nothing auto-applied. -## 4) Version Synchronization Requirements +### 4) Version Synchronization Requirements - **MUST** check for version changes in `package.json` before committing -- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version - changes +- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version changes - **MUST** validate version format consistency between both files -- **MUST** include version bump commits in changelog with proper semantic - versioning - -### Version Sync Checklist (Before Commit) - -- [ ] `package.json` version matches latest `CHANGELOG.md` entry -- [ ] New version follows semantic versioning - (MAJOR.MINOR.PATCH[-PRERELEASE]) -- [ ] Changelog entry includes all significant changes since last version -- [ ] Version bump commit message follows `build(version): bump to X.Y.Z` - format -- [ ] Breaking changes properly documented with migration notes -- [ ] Alert developer in chat message that version has been updated - -### Version Change Detection - -- **Check for version changes** in staged/unstaged `package.json` -- **Alert developer** if version changed but changelog not updated -- **Suggest changelog update** with proper format and content -- **Validate semantic versioning** compliance - -### Implementation Notes - -- **Version Detection**: Compare `package.json` version field with latest - changelog entry -- **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` - format -- **Changelog Format**: Follow [Keep a Changelog](https://keepachangelog.com/) - standards -- **Breaking Changes**: Use `!` in commit message and `BREAKING CHANGE:` - in changelog -- **Pre-release Versions**: Include beta/alpha/rc suffixes in both files - consistently - -## Commit Message Format (Normative) - -### A. Subject Line (required) - -``` -<type>(<scope>)<!>: <summary> -``` - -- **type** (lowercase, Conventional Commits): - `feat|fix|refactor|perf|docs|test|build|chore|ci|revert` -- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`) -- **!**: include when a breaking change is introduced -- **summary**: imperative mood, ≤ 72 chars, no trailing period - -**Examples** - -- `fix(api): handle null token in refresh path` -- `feat(ui/login)!: require OTP after 3 failed attempts` - -### B. Body (optional, when it adds non-obvious value) - -- One blank line after subject. -- Wrap at ~72 chars. -- Explain **what** and **why**, not line-by-line "how". -- Include brief notes like tests passing or TS/lint issues resolved - **only if material**. - -**Body checklist** - -- [ ] Problem/symptom being addressed -- [ ] High-level approach or rationale -- [ ] Risks, tradeoffs, or follow-ups (if any) - -### C. Footer (optional) - -- Issue refs: `Closes #123`, `Refs #456` -- Breaking change (alternative to `!`): - `BREAKING CHANGE: <impact + migration note>` -- Authors: `Co-authored-by: Name <email>` -- Security: `CVE-XXXX-YYYY: <short note>` (if applicable) - -## Content Guidance - -### Include (when relevant) - -- Specific fixes/features delivered -- Symptoms/problems fixed -- Brief note that tests passed or TS/lint errors resolved - -### Avoid - -- Vague: *improved, enhanced, better* -- Trivialities: tiny docs, one-liners, pure lint cleanups (separate, - focused commits if needed) -- Redundancy: generic blurbs repeated across files -- Multi-purpose dumps: keep commits **narrow and focused** -- Long explanations that good inline code comments already cover - -**Guiding Principle:** Let code and inline docs speak. Use commits to -highlight what isn't obvious. - -## Copy-Paste Templates - -### Minimal (no body) - -```text -<type>(<scope>): <summary> -``` - -### Standard (with body & footer) - -```text -<type>(<scope>)<!>: <summary> - -<why-this-change?> -<what-it-does?> -<risks-or-follow-ups?> - -Closes #<id> -BREAKING CHANGE: <impact + migration> -Co-authored-by: <Name> <email> -``` +- **MUST** include version bump commits in changelog with + proper semantic versioning ## Assistant Output Checklist (before showing the draft) @@ -159,177 +45,42 @@ Co-authored-by: <Name> <email> - [ ] Body only if it adds non-obvious value - [ ] No invented changes; aligns strictly with diffs - [ ] Render as a single copy-paste block for the developer +- [ ] No invented changes; aligns strictly with diffs +- [ ] Render as a single copy-paste block for the developer --- +**See also**: + +- `.cursor/rules/workflow/commit_messages.mdc` for commit message format and + templates +- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details + **Status**: Active version control guidelines **Priority**: High **Estimated Effort**: Ongoing reference **Dependencies**: git, package.json, CHANGELOG.md **Stakeholders**: Development team, AI assistants -- [ ] No invented changes; aligns strictly with diffs -- [ ] Render as a single copy-paste block for the developer +## Model Implementation Checklist -## 1) Version-Control Ownership +### Before Version Control Work -- **MUST NOT** run `git add`, `git commit`, or any write action. -- **MUST** leave staging/committing to the developer. +- [ ] **File Analysis**: Review files staged and awaiting staging +- [ ] **Version Check**: Check for version changes in package.json +- [ ] **Changelog Review**: Verify CHANGELOG.md is updated if version changed +- [ ] **Diff Analysis**: Analyze actual changes from git diffs -## 2) Source of Truth for Commit Text +### During Version Control Work -- **MUST** derive messages **only** from: - - files **staged** for commit (primary), and - - files **awaiting staging** (context). -- **MUST** use the **diffs** to inform content. -- **MUST NOT** invent changes or imply work not present in diffs. - -## 3) Mandatory Preview Flow +- [ ] **Commit Preview**: Present file list with brief notes per file +- [ ] **Message Draft**: Provide focused draft commit message +- [ ] **Format Validation**: Ensure message follows type(scope)! syntax +- [ ] **Version Sync**: Validate version consistency between files -- **ALWAYS** present, before any real commit: - - file list + brief per-file notes, - - a **draft commit message** (copy-paste ready), - - nothing auto-applied. - -## 4) Version Synchronization Requirements - -- **MUST** check for version changes in `package.json` before committing -- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version - changes -- **MUST** validate version format consistency between both files -- **MUST** include version bump commits in changelog with proper semantic - versioning - -### Version Sync Checklist (Before Commit) - -- [ ] `package.json` version matches latest `CHANGELOG.md` entry -- [ ] New version follows semantic versioning - (MAJOR.MINOR.PATCH[-PRERELEASE]) -- [ ] Changelog entry includes all significant changes since last version -- [ ] Version bump commit message follows `build(version): bump to X.Y.Z` - format -- [ ] Breaking changes properly documented with migration notes -- [ ] Alert developer in chat message that version has been updated - -### Version Change Detection - -- **Check for version changes** in staged/unstaged `package.json` -- **Alert developer** if version changed but changelog not updated -- **Suggest changelog update** with proper format and content -- **Validate semantic versioning** compliance - -### Implementation Notes - -- **Version Detection**: Compare `package.json` version field with latest - changelog entry -- **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` - format -- **Changelog Format**: Follow [Keep a Changelog](https://keepachangelog.com/) - standards -- **Breaking Changes**: Use `!` in commit message and `BREAKING CHANGE:` - in changelog -- **Pre-release Versions**: Include beta/alpha/rc suffixes in both files - consistently - -## Commit Message Format (Normative) - -### A. Subject Line (required) - -``` -<type>(<scope>)<!>: <summary> -``` - -- **type** (lowercase, Conventional Commits): - `feat|fix|refactor|perf|docs|test|build|chore|ci|revert` -- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`) -- **!**: include when a breaking change is introduced -- **summary**: imperative mood, ≤ 72 chars, no trailing period - -**Examples** - -- `fix(api): handle null token in refresh path` -- `feat(ui/login)!: require OTP after 3 failed attempts` - -### B. Body (optional, when it adds non-obvious value) - -- One blank line after subject. -- Wrap at ~72 chars. -- Explain **what** and **why**, not line-by-line "how". -- Include brief notes like tests passing or TS/lint issues resolved - **only if material**. - -**Body checklist** - -- [ ] Problem/symptom being addressed -- [ ] High-level approach or rationale -- [ ] Risks, tradeoffs, or follow-ups (if any) - -### C. Footer (optional) - -- Issue refs: `Closes #123`, `Refs #456` -- Breaking change (alternative to `!`): - `BREAKING CHANGE: <impact + migration note>` -- Authors: `Co-authored-by: Name <email>` -- Security: `CVE-XXXX-YYYY: <short note>` (if applicable) - -## Content Guidance - -### Include (when relevant) - -- Specific fixes/features delivered -- Symptoms/problems fixed -- Brief note that tests passed or TS/lint errors resolved - -### Avoid - -- Vague: *improved, enhanced, better* -- Trivialities: tiny docs, one-liners, pure lint cleanups (separate, - focused commits if needed) -- Redundancy: generic blurbs repeated across files -- Multi-purpose dumps: keep commits **narrow and focused** -- Long explanations that good inline code comments already cover - -**Guiding Principle:** Let code and inline docs speak. Use commits to -highlight what isn't obvious. - -## Copy-Paste Templates - -### Minimal (no body) - -```text -<type>(<scope>): <summary> -``` - -### Standard (with body & footer) - -```text -<type>(<scope>)<!>: <summary> - -<why-this-change?> -<what-it-does?> -<risks-or-follow-ups?> - -Closes #<id> -BREAKING CHANGE: <impact + migration> -Co-authored-by: <Name> <email> -``` - -## Assistant Output Checklist (before showing the draft) - -- [ ] List changed files + 1–2 line notes per file -- [ ] Provide **one** focused draft message (subject/body/footer) -- [ ] Subject ≤ 72 chars, imperative mood, correct `type(scope)!` syntax -- [ ] Body only if it adds non-obvious value -- [ ] No invented changes; aligns strictly with diffs -- [ ] Render as a single copy-paste block for the developer - ---- - -**Status**: Active version control guidelines -**Priority**: High -**Estimated Effort**: Ongoing reference -**Dependencies**: git, package.json, CHANGELOG.md -**Stakeholders**: Development team, AI assistants +### After Version Control Work -* [ ] No invented changes; aligns strictly with diffs -* [ ] Render as a single copy-paste block for the developer +- [ ] **Developer Control**: Leave staging/committing to developer +- [ ] **Message Validation**: Verify message aligns strictly with diffs +- [ ] **Version Validation**: Confirm version format consistency +- [ ] **Documentation**: Update relevant version control documentation diff --git a/.cursor/rules/workflow/version_sync.mdc b/.cursor/rules/workflow/version_sync.mdc new file mode 100644 index 00000000..3f2d4df9 --- /dev/null +++ b/.cursor/rules/workflow/version_sync.mdc @@ -0,0 +1,176 @@ +# Version Synchronization and Changelog Management + +> **Agent role**: Reference this file for version synchronization +> requirements and changelog management. + +## Version Sync Checklist (Before Commit) + +- [ ] `package.json` version matches latest `CHANGELOG.md` entry +- [ ] New version follows semantic versioning + (MAJOR.MINOR.PATCH[-PRERELEASE]) +- [ ] Changelog entry includes all significant changes since last version +- [ ] Version bump commit message follows `build(version): bump to X.Y.Z` + format +- [ ] Breaking changes properly documented with migration notes +- [ ] Alert developer in chat message that version has been updated + +## Version Change Detection + +- **Check for version changes** in staged/unstaged `package.json` +- **Alert developer** if version changed but changelog not updated +- **Suggest changelog update** with proper format and content +- **Validate semantic versioning** compliance + +## Implementation Notes + +### Version Detection + +- Compare `package.json` version field with latest changelog entry +- Use semantic versioning validation +- Check for pre-release version consistency + +### Semantic Validation + +- Ensure version follows `X.Y.Z[-PRERELEASE]` format +- Validate major.minor.patch components +- Handle pre-release suffixes (beta, alpha, rc) + +### Changelog Format + +- Follow [Keep a Changelog](https://keepachangelog.com/) standards +- Use consistent section headers +- Include breaking change notes +- Maintain chronological order + +### Breaking Changes + +- Use `!` in commit message +- Include `BREAKING CHANGE:` in changelog +- Provide migration notes +- Document impact clearly + +### Pre-release Versions + +- Include beta/alpha/rc suffixes consistently +- Update both `package.json` and changelog +- Maintain version number alignment +- Document pre-release status + +## Changelog Sections + +### Added + +- New features +- New capabilities +- New dependencies + +### Changed + +- Changes in existing functionality +- API changes +- Performance improvements + +### Deprecated + +- Soon-to-be removed features +- Migration paths +- Sunset timelines + +### Removed + +- Removed features +- Breaking changes +- Deprecated items + +### Fixed + +- Bug fixes +- Security patches +- Performance fixes + +### Security + +- Security vulnerabilities +- CVE references +- Mitigation steps + +## Version Bump Guidelines + +### Patch (X.Y.Z+1) + +- Bug fixes +- Documentation updates +- Minor improvements + +### Minor (X.Y+1.Z) + +- New features +- Backward-compatible changes +- Significant improvements + +### Major (X+1.Y.Z) + +- Breaking changes +- Major API changes +- Incompatible changes + +## Pre-release Guidelines + +### Beta Versions + +- Feature complete +- Testing phase +- API stable + +### Alpha Versions + +- Early development +- API may change +- Limited testing + +### Release Candidates + +- Final testing +- API frozen +- Production ready + +--- + +**See also**: + +- `.cursor/rules/workflow/version_control.mdc` for core version + control principles +- `.cursor/rules/workflow/commit_messages.mdc` for commit message + format + +**Status**: Active version synchronization guide +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: version_control.mdc +**Stakeholders**: Development team, Release team + +## Model Implementation Checklist + +### Before Version Changes + +- [ ] **Version Review**: Check current version in `package.json` and `CHANGELOG.md` +- [ ] **Change Assessment**: Identify what type of version bump is needed (patch/minor/major) +- [ ] **Breaking Changes**: Review if any changes are breaking and require + major version +- [ ] **Pre-release Status**: Determine if this should be a pre-release version + +### During Version Synchronization + +- [ ] **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` format +- [ ] **Package Update**: Update `package.json` version field +- [ ] **Changelog Entry**: Add entry to `CHANGELOG.md` following Keep a Changelog + format +- [ ] **Breaking Changes**: Document breaking changes with migration notes + if applicable + +### After Version Changes + +- [ ] **Commit Format**: Use `build(version): bump to X.Y.Z` commit message format +- [ ] **Developer Alert**: Alert developer that version has been updated +- [ ] **Validation**: Verify `package.json` and `CHANGELOG.md` are in sync +- [ ] **Pre-release Handling**: Ensure pre-release versions are consistently formatted diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 00000000..6e881a27 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,53 @@ +{ + // Markdownlint configuration for TimeSafari .cursor/rules + "config": { + // Core formatting rules that can be auto-fixed + "MD013": { + "line_length": 80, + "code_blocks": false, + "tables": false, + "headings": false + }, + "MD012": true, // No multiple consecutive blank lines + "MD022": true, // Headings should be surrounded by blank lines + "MD031": true, // Fenced code blocks should be surrounded by blank lines + "MD032": true, // Lists should be surrounded by blank lines + "MD047": true, // Files should end with a single newline + "MD009": true, // No trailing spaces + "MD010": true, // No hard tabs + "MD004": { "style": "dash" }, // Consistent list markers + "MD029": { "style": "ordered" }, // Ordered list item prefix + + // Disable rules that conflict with existing content structure + "MD041": false, // First line heading requirement + "MD025": false, // Multiple top-level headings + "MD024": false, // Duplicate headings + "MD036": false, // Emphasis as headings + "MD003": false, // Heading style consistency + "MD040": false, // Fenced code language + "MD055": false, // Table pipe style + "MD056": false, // Table column count + "MD034": false, // Bare URLs + "MD023": false // Heading indentation + }, + + "globs": [ + ".cursor/rules/**/*.mdc", + "*.md", + "*.markdown", + "scripts/**/*.md", + "src/**/*.md", + "test-playwright/**/*.md", + "resources/**/*.md", + "doc/**/*.md", + "ios/**/*.md", + "electron/**/*.md" + ], + "ignores": [ + "node_modules/**", + ".git/**", + "**/node_modules/**", + "**/dist/**", + "**/build/**" + ] +} \ No newline at end of file diff --git a/.markdownlint.json b/.markdownlint.json index 2f71b81b..2f13abeb 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1 +1,27 @@ -{"MD013": {"code_blocks": false}} +{ + "MD013": { + "line_length": 80, + "code_blocks": false, + "tables": false, + "headings": false + }, + "MD012": true, + "MD022": true, + "MD031": true, + "MD032": true, + "MD047": true, + "MD009": true, + "MD010": true, + "MD004": { "style": "dash" }, + "MD029": { "style": "ordered" }, + "MD041": false, + "MD025": false, + "MD024": false, + "MD036": false, + "MD003": false, + "MD040": false, + "MD055": false, + "MD056": false, + "MD034": false, + "MD023": false +} \ No newline at end of file diff --git a/package-lock.json b/package-lock.json index 4806f89f..3b1b7baa 100644 --- a/package-lock.json +++ b/package-lock.json @@ -96,6 +96,8 @@ }, "devDependencies": { "@capacitor/assets": "^3.0.5", + "@commitlint/cli": "^18.6.1", + "@commitlint/config-conventional": "^18.6.2", "@playwright/test": "^1.54.2", "@types/dom-webcodecs": "^0.1.7", "@types/jest": "^30.0.0", @@ -123,9 +125,12 @@ "eslint-plugin-prettier": "^5.2.1", "eslint-plugin-vue": "^9.32.0", "fs-extra": "^11.3.0", + "husky": "^9.0.11", "jest": "^30.0.4", + "lint-staged": "^15.2.2", "markdownlint": "^0.37.4", "markdownlint-cli": "^0.44.0", + "markdownlint-cli2": "^0.18.1", "npm-check-updates": "^17.1.13", "path-browserify": "^1.0.1", "postcss": "^8.4.38", @@ -2429,311 +2434,533 @@ "win32" ] }, - "node_modules/@cspotcode/source-map-support": { - "version": "0.8.1", - "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", - "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", - "devOptional": true, + "node_modules/@commitlint/cli": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/cli/-/cli-18.6.1.tgz", + "integrity": "sha512-5IDE0a+lWGdkOvKH892HHAZgbAjcj1mT5QrfA/SVbLJV/BbBMGyKN0W5mhgjekPJJwEQdVNvhl9PwUacY58Usw==", + "dev": true, "license": "MIT", "dependencies": { - "@jridgewell/trace-mapping": "0.3.9" + "@commitlint/format": "^18.6.1", + "@commitlint/lint": "^18.6.1", + "@commitlint/load": "^18.6.1", + "@commitlint/read": "^18.6.1", + "@commitlint/types": "^18.6.1", + "execa": "^5.0.0", + "lodash.isfunction": "^3.0.9", + "resolve-from": "5.0.0", + "resolve-global": "1.0.0", + "yargs": "^17.0.0" + }, + "bin": { + "commitlint": "cli.js" }, "engines": { - "node": ">=12" + "node": ">=v18" } }, - "node_modules/@cspotcode/source-map-support/node_modules/@jridgewell/trace-mapping": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", - "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", - "devOptional": true, + "node_modules/@commitlint/cli/node_modules/resolve-from": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz", + "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==", + "dev": true, "license": "MIT", - "dependencies": { - "@jridgewell/resolve-uri": "^3.0.3", - "@jridgewell/sourcemap-codec": "^1.4.10" + "engines": { + "node": ">=8" } }, - "node_modules/@develar/schema-utils": { - "version": "2.6.5", - "resolved": "https://registry.npmjs.org/@develar/schema-utils/-/schema-utils-2.6.5.tgz", - "integrity": "sha512-0cp4PsWQ/9avqTVMCtZ+GirikIA36ikvjtHweU4/j8yLtgObI0+JUPhYFScgwlteveGB1rt3Cm8UhN04XayDig==", + "node_modules/@commitlint/config-conventional": { + "version": "18.6.3", + "resolved": "https://registry.npmjs.org/@commitlint/config-conventional/-/config-conventional-18.6.3.tgz", + "integrity": "sha512-8ZrRHqF6je+TRaFoJVwszwnOXb/VeYrPmTwPhf0WxpzpGTcYy1p0SPyZ2eRn/sRi/obnWAcobtDAq6+gJQQNhQ==", + "dev": true, "license": "MIT", "dependencies": { - "ajv": "^6.12.0", - "ajv-keywords": "^3.4.1" + "@commitlint/types": "^18.6.1", + "conventional-changelog-conventionalcommits": "^7.0.2" }, "engines": { - "node": ">= 8.9.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/webpack" + "node": ">=v18" } }, - "node_modules/@dicebear/adventurer": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/adventurer/-/adventurer-5.4.3.tgz", - "integrity": "sha512-PYv82wc1kwhFeyvZYKUIzOoaSNvRj5yn72yRCTlT3K4qoChKPGIJ7K/GoFoNX3Cj0XAWSkp0shPsGFtpU1o3Kg==", - "license": "MIT", - "engines": { - "node": "^14.13.1 || >=16.0.0" + "node_modules/@commitlint/config-conventional/node_modules/conventional-changelog-conventionalcommits": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/conventional-changelog-conventionalcommits/-/conventional-changelog-conventionalcommits-7.0.2.tgz", + "integrity": "sha512-NKXYmMR/Hr1DevQegFB4MwfM5Vv0m4UIxKZTTYuD98lpTknaZlSRrDOG4X7wIXpGkfsYxZTghUN+Qq+T0YQI7w==", + "dev": true, + "license": "ISC", + "dependencies": { + "compare-func": "^2.0.0" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "engines": { + "node": ">=16" } }, - "node_modules/@dicebear/adventurer-neutral": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/adventurer-neutral/-/adventurer-neutral-5.4.3.tgz", - "integrity": "sha512-FdprrUE0zXRlx4UAu5ED+wFkxwNSQSJug+lvNjTQtA675c52kkuct/U9eCcD4vcSAd38v4IIKVBMLP/1tEBVXQ==", + "node_modules/@commitlint/config-validator": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/config-validator/-/config-validator-18.6.1.tgz", + "integrity": "sha512-05uiToBVfPhepcQWE1ZQBR/Io3+tb3gEotZjnI4tTzzPk16NffN6YABgwFQCLmzZefbDcmwWqJWc2XT47q7Znw==", + "dev": true, "license": "MIT", - "engines": { - "node": "^14.13.1 || >=16.0.0" + "dependencies": { + "@commitlint/types": "^18.6.1", + "ajv": "^8.11.0" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "engines": { + "node": ">=v18" } }, - "node_modules/@dicebear/avataaars": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/avataaars/-/avataaars-5.4.3.tgz", - "integrity": "sha512-/zC/IPCI/JOsR6gUmXLo9HH2GFujHSvWfqYf23/n8V4e9Dm0gJ3RtZ/g9Kn+6Rkd8hiNp0BUzjlSEwiONEVOug==", + "node_modules/@commitlint/config-validator/node_modules/ajv": { + "version": "8.17.1", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", + "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", + "dev": true, "license": "MIT", - "engines": { - "node": "^14.13.1 || >=16.0.0" + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" } }, - "node_modules/@dicebear/avataaars-neutral": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/avataaars-neutral/-/avataaars-neutral-5.4.3.tgz", - "integrity": "sha512-3hV80zzqpn2tHaitRqRqokxJ/h5vD4YXwMtdvXJq6AKCVcUiVi9ecHVP3GU4uU2zPSk7VsbadVQMXy7/Z47nRw==", + "node_modules/@commitlint/config-validator/node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "dev": true, + "license": "MIT" + }, + "node_modules/@commitlint/ensure": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/ensure/-/ensure-18.6.1.tgz", + "integrity": "sha512-BPm6+SspyxQ7ZTsZwXc7TRQL5kh5YWt3euKmEIBZnocMFkJevqs3fbLRb8+8I/cfbVcAo4mxRlpTPfz8zX7SnQ==", + "dev": true, "license": "MIT", - "engines": { - "node": "^14.13.1 || >=16.0.0" + "dependencies": { + "@commitlint/types": "^18.6.1", + "lodash.camelcase": "^4.3.0", + "lodash.kebabcase": "^4.1.1", + "lodash.snakecase": "^4.1.1", + "lodash.startcase": "^4.4.0", + "lodash.upperfirst": "^4.3.1" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "engines": { + "node": ">=v18" } }, - "node_modules/@dicebear/big-ears": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/big-ears/-/big-ears-5.4.3.tgz", - "integrity": "sha512-MXr0m0JNAGbxDt/onoIeIclOgUZbM1eHzH+i+uyz+9mK10IZPysV5i71cL84ZFDBEEWMKVi3uWfr1sCdck3+eQ==", + "node_modules/@commitlint/execute-rule": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/execute-rule/-/execute-rule-18.6.1.tgz", + "integrity": "sha512-7s37a+iWyJiGUeMFF6qBlyZciUkF8odSAnHijbD36YDctLhGKoYltdvuJ/AFfRm6cBLRtRk9cCVPdsEFtt/2rg==", + "dev": true, "license": "MIT", "engines": { - "node": "^14.13.1 || >=16.0.0" - }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "node": ">=v18" } }, - "node_modules/@dicebear/big-ears-neutral": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/big-ears-neutral/-/big-ears-neutral-5.4.3.tgz", - "integrity": "sha512-uMt1MvnQ6pCL0u3rpjeEjryLs5MLLcYkAkidFZ6CpziiQyehkaI/1PwZlv7/zG7CD5wZTmUQKZ5+0U4fWR8rwg==", + "node_modules/@commitlint/format": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/format/-/format-18.6.1.tgz", + "integrity": "sha512-K8mNcfU/JEFCharj2xVjxGSF+My+FbUHoqR+4GqPGrHNqXOGNio47ziiR4HQUPKtiNs05o8/WyLBoIpMVOP7wg==", + "dev": true, "license": "MIT", - "engines": { - "node": "^14.13.1 || >=16.0.0" + "dependencies": { + "@commitlint/types": "^18.6.1", + "chalk": "^4.1.0" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "engines": { + "node": ">=v18" } }, - "node_modules/@dicebear/big-smile": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/big-smile/-/big-smile-5.4.3.tgz", - "integrity": "sha512-JIBi6L9CcEhLE83CpHw/JskF7kmD4t+vIeAU95WNPm3c98lLe7h2k2ocDVnZEKpBUqxKG3lk0rFXoYM5ovSpLw==", + "node_modules/@commitlint/is-ignored": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/is-ignored/-/is-ignored-18.6.1.tgz", + "integrity": "sha512-MOfJjkEJj/wOaPBw5jFjTtfnx72RGwqYIROABudOtJKW7isVjFe9j0t8xhceA02QebtYf4P/zea4HIwnXg8rvA==", + "dev": true, "license": "MIT", - "engines": { - "node": "^14.13.1 || >=16.0.0" + "dependencies": { + "@commitlint/types": "^18.6.1", + "semver": "7.6.0" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "engines": { + "node": ">=v18" } }, - "node_modules/@dicebear/bottts": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/bottts/-/bottts-5.4.3.tgz", - "integrity": "sha512-yhuIB+8ptZzZgDGYOqNXplELoU/In/5zeiqsHEkJtjAEJZd6BEDqUYMHnB1IgUAic9L3gvPt7t3cv2fPbrFDPQ==", - "license": "MIT", + "node_modules/@commitlint/is-ignored/node_modules/lru-cache": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz", + "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==", + "dev": true, + "license": "ISC", + "dependencies": { + "yallist": "^4.0.0" + }, "engines": { - "node": "^14.13.1 || >=16.0.0" + "node": ">=10" + } + }, + "node_modules/@commitlint/is-ignored/node_modules/semver": { + "version": "7.6.0", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.6.0.tgz", + "integrity": "sha512-EnwXhrlwXMk9gKu5/flx5sv/an57AkRplG3hTK68W7FRDN+k+OWBj65M7719OkA82XLBxrcX0KSHj+X5COhOVg==", + "dev": true, + "license": "ISC", + "dependencies": { + "lru-cache": "^6.0.0" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" } }, - "node_modules/@dicebear/bottts-neutral": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/bottts-neutral/-/bottts-neutral-5.4.3.tgz", - "integrity": "sha512-92mHaeDDblsF5fxX6f8JIYEGxBdIOhnVPNh88XejHBW4RBSyCvXgGVMvmnh6j4YTRoTQHObTCrxdbll4LG4qtQ==", + "node_modules/@commitlint/lint": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/lint/-/lint-18.6.1.tgz", + "integrity": "sha512-8WwIFo3jAuU+h1PkYe5SfnIOzp+TtBHpFr4S8oJWhu44IWKuVx6GOPux3+9H1iHOan/rGBaiacicZkMZuluhfQ==", + "dev": true, "license": "MIT", - "engines": { - "node": "^14.13.1 || >=16.0.0" + "dependencies": { + "@commitlint/is-ignored": "^18.6.1", + "@commitlint/parse": "^18.6.1", + "@commitlint/rules": "^18.6.1", + "@commitlint/types": "^18.6.1" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "engines": { + "node": ">=v18" } }, - "node_modules/@dicebear/collection": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/collection/-/collection-5.4.3.tgz", - "integrity": "sha512-iy+NWb4LL0LtYzxizzpXX7iP1WWFFatlEc8WjAsP6y+eKPXz7DWX0k5uJDEbHmJXpHEpvmaowV8evcL07iHwdw==", + "node_modules/@commitlint/load": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/load/-/load-18.6.1.tgz", + "integrity": "sha512-p26x8734tSXUHoAw0ERIiHyW4RaI4Bj99D8YgUlVV9SedLf8hlWAfyIFhHRIhfPngLlCe0QYOdRKYFt8gy56TA==", + "dev": true, "license": "MIT", "dependencies": { - "@dicebear/adventurer": "5.4.3", - "@dicebear/adventurer-neutral": "5.4.3", - "@dicebear/avataaars": "5.4.3", - "@dicebear/avataaars-neutral": "5.4.3", - "@dicebear/big-ears": "5.4.3", - "@dicebear/big-ears-neutral": "5.4.3", - "@dicebear/big-smile": "5.4.3", - "@dicebear/bottts": "5.4.3", - "@dicebear/bottts-neutral": "5.4.3", - "@dicebear/croodles": "5.4.3", - "@dicebear/croodles-neutral": "5.4.3", - "@dicebear/fun-emoji": "5.4.3", - "@dicebear/icons": "5.4.3", - "@dicebear/identicon": "5.4.3", - "@dicebear/initials": "5.4.3", - "@dicebear/lorelei": "5.4.3", - "@dicebear/lorelei-neutral": "5.4.3", - "@dicebear/micah": "5.4.3", - "@dicebear/miniavs": "5.4.3", - "@dicebear/open-peeps": "5.4.3", - "@dicebear/personas": "5.4.3", - "@dicebear/pixel-art": "5.4.3", - "@dicebear/pixel-art-neutral": "5.4.3", - "@dicebear/shapes": "5.4.3", - "@dicebear/thumbs": "5.4.3" + "@commitlint/config-validator": "^18.6.1", + "@commitlint/execute-rule": "^18.6.1", + "@commitlint/resolve-extends": "^18.6.1", + "@commitlint/types": "^18.6.1", + "chalk": "^4.1.0", + "cosmiconfig": "^8.3.6", + "cosmiconfig-typescript-loader": "^5.0.0", + "lodash.isplainobject": "^4.0.6", + "lodash.merge": "^4.6.2", + "lodash.uniq": "^4.5.0", + "resolve-from": "^5.0.0" }, "engines": { - "node": "^14.13.1 || >=16.0.0" - }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "node": ">=v18" } }, - "node_modules/@dicebear/converter": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/converter/-/converter-5.4.3.tgz", - "integrity": "sha512-7gXwzNfQf5v7JVOyeuOetP59NxYewOLr6QNZaV/+/Did6B6dUJqvAsHWOhmf/JEWJFDkh/6cyGZEgpM4eSxW4A==", + "node_modules/@commitlint/load/node_modules/cosmiconfig": { + "version": "8.3.6", + "resolved": "https://registry.npmjs.org/cosmiconfig/-/cosmiconfig-8.3.6.tgz", + "integrity": "sha512-kcZ6+W5QzcJ3P1Mt+83OUv/oHFqZHIx8DuxG6eZ5RGMERoLqp4BuGjhHLYGK+Kf5XVkQvqBSmAy/nGWN3qDgEA==", + "dev": true, "license": "MIT", "dependencies": { - "@types/json-schema": "^7.0.7", - "tmp-promise": "^3.0.3" + "import-fresh": "^3.3.0", + "js-yaml": "^4.1.0", + "parse-json": "^5.2.0", + "path-type": "^4.0.0" }, "engines": { - "node": "^14.13.1 || >=16.0.0" + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/d-fischer" }, "peerDependencies": { - "@resvg/resvg-js": "^2.0.0", - "exiftool-vendored": "^16 || ^17 || ^18 || ^19 || ^20 || ^21", - "sharp": "^0.32.6" + "typescript": ">=4.9.5" }, "peerDependenciesMeta": { - "@resvg/resvg-js": { - "optional": true - }, - "exiftool-vendored": { - "optional": true - }, - "sharp": { + "typescript": { "optional": true } } }, - "node_modules/@dicebear/core": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/core/-/core-5.4.3.tgz", - "integrity": "sha512-qOOlqdVD1CWT0VFxABADP62oPF8WosfE+OkREYD+vZ3T7rq8kauHAUbGkvwRoB60uMld7kfZzEJNhjR7QI22IQ==", + "node_modules/@commitlint/load/node_modules/cosmiconfig-typescript-loader": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/cosmiconfig-typescript-loader/-/cosmiconfig-typescript-loader-5.1.0.tgz", + "integrity": "sha512-7PtBB+6FdsOvZyJtlF3hEPpACq7RQX6BVGsgC7/lfVXnKMvNCu/XY3ykreqG5w/rBNdu2z8LCIKoF3kpHHdHlA==", + "dev": true, "license": "MIT", "dependencies": { - "@dicebear/converter": "5.4.3" + "jiti": "^1.21.6" }, "engines": { - "node": "^14.13.1 || >=16.0.0" - } - }, - "node_modules/@dicebear/croodles": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/croodles/-/croodles-5.4.3.tgz", - "integrity": "sha512-eP+BwAb7Pm8msS+hcIMyfleBYSqGngt2Ocu/cNqZV2kSLkfIOrogSb4VJTkVtwbJd2Gpt41d+AxW71QSLN2ARQ==", - "license": "MIT", - "engines": { - "node": "^14.13.1 || >=16.0.0" + "node": ">=v16" }, "peerDependencies": { - "@dicebear/core": "^5.0.0" + "@types/node": "*", + "cosmiconfig": ">=8.2", + "typescript": ">=4" } }, - "node_modules/@dicebear/croodles-neutral": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/croodles-neutral/-/croodles-neutral-5.4.3.tgz", - "integrity": "sha512-Z4wGeeUEdZjer6xKy5jimgDXQtUnW1OKQuV+LjA6bgyLTB/QmtmspZHzqCOgwZFQAydqcUoxEFWmrIpwNLujBA==", + "node_modules/@commitlint/load/node_modules/resolve-from": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz", + "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==", + "dev": true, "license": "MIT", "engines": { - "node": "^14.13.1 || >=16.0.0" - }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "node": ">=8" } }, - "node_modules/@dicebear/fun-emoji": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/fun-emoji/-/fun-emoji-5.4.3.tgz", - "integrity": "sha512-La4XonWV0abaIiE4Dj0OOtH7tH5VC1tiXmcapJJ69d3y6YfJnedyhHzD+Xk2gnWFD/X0mnmLJua++BGSrv7YkQ==", + "node_modules/@commitlint/message": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/message/-/message-18.6.1.tgz", + "integrity": "sha512-VKC10UTMLcpVjMIaHHsY1KwhuTQtdIKPkIdVEwWV+YuzKkzhlI3aNy6oo1eAN6b/D2LTtZkJe2enHmX0corYRw==", + "dev": true, "license": "MIT", "engines": { - "node": "^14.13.1 || >=16.0.0" + "node": ">=v18" + } + }, + "node_modules/@commitlint/parse": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/parse/-/parse-18.6.1.tgz", + "integrity": "sha512-eS/3GREtvVJqGZrwAGRwR9Gdno3YcZ6Xvuaa+vUF8j++wsmxrA2En3n0ccfVO2qVOLJC41ni7jSZhQiJpMPGOQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@commitlint/types": "^18.6.1", + "conventional-changelog-angular": "^7.0.0", + "conventional-commits-parser": "^5.0.0" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "engines": { + "node": ">=v18" } }, - "node_modules/@dicebear/icons": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/icons/-/icons-5.4.3.tgz", - "integrity": "sha512-p173l+PkZBrVtUTgSFVD9dHLc9djkRtxp+tLNsGYkBjeeWmJ/kxtPH5iG7MOp1pUnCHRkWJrLyysV51sgcrNug==", + "node_modules/@commitlint/parse/node_modules/conventional-changelog-angular": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/conventional-changelog-angular/-/conventional-changelog-angular-7.0.0.tgz", + "integrity": "sha512-ROjNchA9LgfNMTTFSIWPzebCwOGFdgkEq45EnvvrmSLvCtAw0HSmrCs7/ty+wAeYUZyNay0YMUNYFTRL72PkBQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "compare-func": "^2.0.0" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/@commitlint/parse/node_modules/conventional-commits-parser": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/conventional-commits-parser/-/conventional-commits-parser-5.0.0.tgz", + "integrity": "sha512-ZPMl0ZJbw74iS9LuX9YIAiW8pfM5p3yh2o/NbXHbkFuZzY5jvdi5jFycEOkmBW5H5I7nA+D6f3UcsCLP2vvSEA==", + "dev": true, "license": "MIT", + "dependencies": { + "is-text-path": "^2.0.0", + "JSONStream": "^1.3.5", + "meow": "^12.0.1", + "split2": "^4.0.0" + }, + "bin": { + "conventional-commits-parser": "cli.mjs" + }, "engines": { - "node": "^14.13.1 || >=16.0.0" + "node": ">=16" + } + }, + "node_modules/@commitlint/parse/node_modules/is-text-path": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/is-text-path/-/is-text-path-2.0.0.tgz", + "integrity": "sha512-+oDTluR6WEjdXEJMnC2z6A4FRwFoYuvShVVEGsS7ewc0UTi2QtAKMDJuL4BDEVt+5T7MjFo12RP8ghOM75oKJw==", + "dev": true, + "license": "MIT", + "dependencies": { + "text-extensions": "^2.0.0" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "engines": { + "node": ">=8" } }, - "node_modules/@dicebear/identicon": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/identicon/-/identicon-5.4.3.tgz", - "integrity": "sha512-it9tHCJ9UWdSwDzbYZVDhx8mZMQKeKXIWzmOWwS/aGHM3aONn8Kjxd6m5rnQGWFVzxxUjedrIOZxFhWuogzYOw==", + "node_modules/@commitlint/parse/node_modules/meow": { + "version": "12.1.1", + "resolved": "https://registry.npmjs.org/meow/-/meow-12.1.1.tgz", + "integrity": "sha512-BhXM0Au22RwUneMPwSCnyhTOizdWoIEPU9sp0Aqa1PnDMR5Wv2FGXYDjuzJEIX+Eo2Rb8xuYe5jrnm5QowQFkw==", + "dev": true, "license": "MIT", "engines": { - "node": "^14.13.1 || >=16.0.0" + "node": ">=16.10" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "funding": { + "url": "https://github.com/sponsors/sindresorhus" } }, - "node_modules/@dicebear/initials": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/initials/-/initials-5.4.3.tgz", - "integrity": "sha512-SkCxoo+llqJoOXQsVoJvruQhN4QCLOOtBvNsg7aO0W0MIYPWkJoGkpzKhXVuRBEsmI/QOBfkLMBFBpiHz22n4w==", + "node_modules/@commitlint/parse/node_modules/split2": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz", + "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">= 10.x" + } + }, + "node_modules/@commitlint/parse/node_modules/text-extensions": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/text-extensions/-/text-extensions-2.4.0.tgz", + "integrity": "sha512-te/NtwBwfiNRLf9Ijqx3T0nlqZiQ2XrrtBvu+cLL8ZRrGkO0NHTug8MYFKyoSrv/sHTaSKfilUkizV6XhxMJ3g==", + "dev": true, "license": "MIT", "engines": { - "node": "^14.13.1 || >=16.0.0" + "node": ">=8" }, - "peerDependencies": { - "@dicebear/core": "^5.0.0" + "funding": { + "url": "https://github.com/sponsors/sindresorhus" } }, - "node_modules/@dicebear/lorelei": { + "node_modules/@commitlint/read": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/read/-/read-18.6.1.tgz", + "integrity": "sha512-ia6ODaQFzXrVul07ffSgbZGFajpe8xhnDeLIprLeyfz3ivQU1dIoHp7yz0QIorZ6yuf4nlzg4ZUkluDrGN/J/w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@commitlint/top-level": "^18.6.1", + "@commitlint/types": "^18.6.1", + "git-raw-commits": "^2.0.11", + "minimist": "^1.2.6" + }, + "engines": { + "node": ">=v18" + } + }, + "node_modules/@commitlint/resolve-extends": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/resolve-extends/-/resolve-extends-18.6.1.tgz", + "integrity": "sha512-ifRAQtHwK+Gj3Bxj/5chhc4L2LIc3s30lpsyW67yyjsETR6ctHAHRu1FSpt0KqahK5xESqoJ92v6XxoDRtjwEQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@commitlint/config-validator": "^18.6.1", + "@commitlint/types": "^18.6.1", + "import-fresh": "^3.0.0", + "lodash.mergewith": "^4.6.2", + "resolve-from": "^5.0.0", + "resolve-global": "^1.0.0" + }, + "engines": { + "node": ">=v18" + } + }, + "node_modules/@commitlint/resolve-extends/node_modules/resolve-from": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz", + "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/@commitlint/rules": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/rules/-/rules-18.6.1.tgz", + "integrity": "sha512-kguM6HxZDtz60v/zQYOe0voAtTdGybWXefA1iidjWYmyUUspO1zBPQEmJZ05/plIAqCVyNUTAiRPWIBKLCrGew==", + "dev": true, + "license": "MIT", + "dependencies": { + "@commitlint/ensure": "^18.6.1", + "@commitlint/message": "^18.6.1", + "@commitlint/to-lines": "^18.6.1", + "@commitlint/types": "^18.6.1", + "execa": "^5.0.0" + }, + "engines": { + "node": ">=v18" + } + }, + "node_modules/@commitlint/to-lines": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/to-lines/-/to-lines-18.6.1.tgz", + "integrity": "sha512-Gl+orGBxYSNphx1+83GYeNy5N0dQsHBQ9PJMriaLQDB51UQHCVLBT/HBdOx5VaYksivSf5Os55TLePbRLlW50Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=v18" + } + }, + "node_modules/@commitlint/top-level": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/top-level/-/top-level-18.6.1.tgz", + "integrity": "sha512-HyiHQZUTf0+r0goTCDs/bbVv/LiiQ7AVtz6KIar+8ZrseB9+YJAIo8HQ2IC2QT1y3N1lbW6OqVEsTHjbT6hGSw==", + "dev": true, + "license": "MIT", + "dependencies": { + "find-up": "^5.0.0" + }, + "engines": { + "node": ">=v18" + } + }, + "node_modules/@commitlint/types": { + "version": "18.6.1", + "resolved": "https://registry.npmjs.org/@commitlint/types/-/types-18.6.1.tgz", + "integrity": "sha512-gwRLBLra/Dozj2OywopeuHj2ac26gjGkz2cZ+86cTJOdtWfiRRr4+e77ZDAGc6MDWxaWheI+mAV5TLWWRwqrFg==", + "dev": true, + "license": "MIT", + "dependencies": { + "chalk": "^4.1.0" + }, + "engines": { + "node": ">=v18" + } + }, + "node_modules/@cspotcode/source-map-support": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", + "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.9" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@cspotcode/source-map-support/node_modules/@jridgewell/trace-mapping": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", + "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.0.3", + "@jridgewell/sourcemap-codec": "^1.4.10" + } + }, + "node_modules/@develar/schema-utils": { + "version": "2.6.5", + "resolved": "https://registry.npmjs.org/@develar/schema-utils/-/schema-utils-2.6.5.tgz", + "integrity": "sha512-0cp4PsWQ/9avqTVMCtZ+GirikIA36ikvjtHweU4/j8yLtgObI0+JUPhYFScgwlteveGB1rt3Cm8UhN04XayDig==", + "license": "MIT", + "dependencies": { + "ajv": "^6.12.0", + "ajv-keywords": "^3.4.1" + }, + "engines": { + "node": ">= 8.9.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/webpack" + } + }, + "node_modules/@dicebear/adventurer": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/lorelei/-/lorelei-5.4.3.tgz", - "integrity": "sha512-/Zn8lzt0ZCc/S2iPfrSbHqJLa6wh5AoB5S9LclhOmksZqU7RLcjF86wyrwcbg/QZFxMSxvPr8ihL7SbkbRHh3g==", + "resolved": "https://registry.npmjs.org/@dicebear/adventurer/-/adventurer-5.4.3.tgz", + "integrity": "sha512-PYv82wc1kwhFeyvZYKUIzOoaSNvRj5yn72yRCTlT3K4qoChKPGIJ7K/GoFoNX3Cj0XAWSkp0shPsGFtpU1o3Kg==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2742,10 +2969,10 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/lorelei-neutral": { + "node_modules/@dicebear/adventurer-neutral": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/lorelei-neutral/-/lorelei-neutral-5.4.3.tgz", - "integrity": "sha512-eJdnpIAUPXfYiXr+9Kt4r8dDKGiDKc3SliXcqwcEiHnM54k6p6EnAM54SxbxgVsGfKfhB4RxZo2CX1CiENwxUA==", + "resolved": "https://registry.npmjs.org/@dicebear/adventurer-neutral/-/adventurer-neutral-5.4.3.tgz", + "integrity": "sha512-FdprrUE0zXRlx4UAu5ED+wFkxwNSQSJug+lvNjTQtA675c52kkuct/U9eCcD4vcSAd38v4IIKVBMLP/1tEBVXQ==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2754,10 +2981,10 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/micah": { + "node_modules/@dicebear/avataaars": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/micah/-/micah-5.4.3.tgz", - "integrity": "sha512-2seJqhL2a/AV233nPVuFkY7IBW9EUjB+eRYQTYHqkOfgbnExtS7t7jjC57Ot7+FHvvrMjH43r96CKBvMWHKfJw==", + "resolved": "https://registry.npmjs.org/@dicebear/avataaars/-/avataaars-5.4.3.tgz", + "integrity": "sha512-/zC/IPCI/JOsR6gUmXLo9HH2GFujHSvWfqYf23/n8V4e9Dm0gJ3RtZ/g9Kn+6Rkd8hiNp0BUzjlSEwiONEVOug==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2766,10 +2993,10 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/miniavs": { + "node_modules/@dicebear/avataaars-neutral": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/miniavs/-/miniavs-5.4.3.tgz", - "integrity": "sha512-+L3YCUuqf1ufPbAMgVGAXPGT81a+4gPJKPn3mqYSpBY6l4xUUku8MPg0K3JDU1T/801ABT4VXkcIlHwgEz2HIg==", + "resolved": "https://registry.npmjs.org/@dicebear/avataaars-neutral/-/avataaars-neutral-5.4.3.tgz", + "integrity": "sha512-3hV80zzqpn2tHaitRqRqokxJ/h5vD4YXwMtdvXJq6AKCVcUiVi9ecHVP3GU4uU2zPSk7VsbadVQMXy7/Z47nRw==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2778,10 +3005,10 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/open-peeps": { + "node_modules/@dicebear/big-ears": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/open-peeps/-/open-peeps-5.4.3.tgz", - "integrity": "sha512-Xp/7uJBv+iCLG06e7+8KOVI7uDjk5YVj0cZpa6O+03kRF2sdglG8SBKPdT+l5iIxhAK0Yth4vzZZpjsiEqD+Jg==", + "resolved": "https://registry.npmjs.org/@dicebear/big-ears/-/big-ears-5.4.3.tgz", + "integrity": "sha512-MXr0m0JNAGbxDt/onoIeIclOgUZbM1eHzH+i+uyz+9mK10IZPysV5i71cL84ZFDBEEWMKVi3uWfr1sCdck3+eQ==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2790,10 +3017,10 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/personas": { + "node_modules/@dicebear/big-ears-neutral": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/personas/-/personas-5.4.3.tgz", - "integrity": "sha512-Anb1ICUcA/inrGV3FxGV9KJhsOLegpFo5VOWqyqZ/EbpVf77rgNZCj7GfwyzWuSYMKsnURpbxdTVlCn2LigHeA==", + "resolved": "https://registry.npmjs.org/@dicebear/big-ears-neutral/-/big-ears-neutral-5.4.3.tgz", + "integrity": "sha512-uMt1MvnQ6pCL0u3rpjeEjryLs5MLLcYkAkidFZ6CpziiQyehkaI/1PwZlv7/zG7CD5wZTmUQKZ5+0U4fWR8rwg==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2802,10 +3029,10 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/pixel-art": { + "node_modules/@dicebear/big-smile": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/pixel-art/-/pixel-art-5.4.3.tgz", - "integrity": "sha512-itCXZoH5jiVq+yhRMlWyol1TiVJgx/mlZZFcEmIO2tye1QSRWG9fhC4OGln7uvQ8GpLx1cRcVBdHVFA83nuYkQ==", + "resolved": "https://registry.npmjs.org/@dicebear/big-smile/-/big-smile-5.4.3.tgz", + "integrity": "sha512-JIBi6L9CcEhLE83CpHw/JskF7kmD4t+vIeAU95WNPm3c98lLe7h2k2ocDVnZEKpBUqxKG3lk0rFXoYM5ovSpLw==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2814,10 +3041,10 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/pixel-art-neutral": { + "node_modules/@dicebear/bottts": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/pixel-art-neutral/-/pixel-art-neutral-5.4.3.tgz", - "integrity": "sha512-giztLosESV1u7Slkl+B/wLSuWTAvhXvVHHmvbM+jouWTM2prKlI+pyrO/02bRl4rXcW49OHmUVIZLyBFZXpaWA==", + "resolved": "https://registry.npmjs.org/@dicebear/bottts/-/bottts-5.4.3.tgz", + "integrity": "sha512-yhuIB+8ptZzZgDGYOqNXplELoU/In/5zeiqsHEkJtjAEJZd6BEDqUYMHnB1IgUAic9L3gvPt7t3cv2fPbrFDPQ==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2826,10 +3053,10 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/shapes": { + "node_modules/@dicebear/bottts-neutral": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/shapes/-/shapes-5.4.3.tgz", - "integrity": "sha512-42l2bpAufWkoqW1qzj0A4s5vwqoEtTUfjAl5/WrqNiN9EUFIG05dz5po8CWVe7rmUBuwwRKxhj9zZ7yArtQQ6Q==", + "resolved": "https://registry.npmjs.org/@dicebear/bottts-neutral/-/bottts-neutral-5.4.3.tgz", + "integrity": "sha512-92mHaeDDblsF5fxX6f8JIYEGxBdIOhnVPNh88XejHBW4RBSyCvXgGVMvmnh6j4YTRoTQHObTCrxdbll4LG4qtQ==", "license": "MIT", "engines": { "node": "^14.13.1 || >=16.0.0" @@ -2838,11 +3065,38 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@dicebear/thumbs": { + "node_modules/@dicebear/collection": { "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@dicebear/thumbs/-/thumbs-5.4.3.tgz", - "integrity": "sha512-9R8MbVkRsOXPJK4+YZ8hx8WqAPls4Ngf1ol1AQvtsU3qXs4hgTsR9Wz2h9pf+IU3dV4JaF53ubGrxWdncKYZig==", + "resolved": "https://registry.npmjs.org/@dicebear/collection/-/collection-5.4.3.tgz", + "integrity": "sha512-iy+NWb4LL0LtYzxizzpXX7iP1WWFFatlEc8WjAsP6y+eKPXz7DWX0k5uJDEbHmJXpHEpvmaowV8evcL07iHwdw==", "license": "MIT", + "dependencies": { + "@dicebear/adventurer": "5.4.3", + "@dicebear/adventurer-neutral": "5.4.3", + "@dicebear/avataaars": "5.4.3", + "@dicebear/avataaars-neutral": "5.4.3", + "@dicebear/big-ears": "5.4.3", + "@dicebear/big-ears-neutral": "5.4.3", + "@dicebear/big-smile": "5.4.3", + "@dicebear/bottts": "5.4.3", + "@dicebear/bottts-neutral": "5.4.3", + "@dicebear/croodles": "5.4.3", + "@dicebear/croodles-neutral": "5.4.3", + "@dicebear/fun-emoji": "5.4.3", + "@dicebear/icons": "5.4.3", + "@dicebear/identicon": "5.4.3", + "@dicebear/initials": "5.4.3", + "@dicebear/lorelei": "5.4.3", + "@dicebear/lorelei-neutral": "5.4.3", + "@dicebear/micah": "5.4.3", + "@dicebear/miniavs": "5.4.3", + "@dicebear/open-peeps": "5.4.3", + "@dicebear/personas": "5.4.3", + "@dicebear/pixel-art": "5.4.3", + "@dicebear/pixel-art-neutral": "5.4.3", + "@dicebear/shapes": "5.4.3", + "@dicebear/thumbs": "5.4.3" + }, "engines": { "node": "^14.13.1 || >=16.0.0" }, @@ -2850,7 +3104,240 @@ "@dicebear/core": "^5.0.0" } }, - "node_modules/@digitalbazaar/bitstring": { + "node_modules/@dicebear/converter": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/converter/-/converter-5.4.3.tgz", + "integrity": "sha512-7gXwzNfQf5v7JVOyeuOetP59NxYewOLr6QNZaV/+/Did6B6dUJqvAsHWOhmf/JEWJFDkh/6cyGZEgpM4eSxW4A==", + "license": "MIT", + "dependencies": { + "@types/json-schema": "^7.0.7", + "tmp-promise": "^3.0.3" + }, + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@resvg/resvg-js": "^2.0.0", + "exiftool-vendored": "^16 || ^17 || ^18 || ^19 || ^20 || ^21", + "sharp": "^0.32.6" + }, + "peerDependenciesMeta": { + "@resvg/resvg-js": { + "optional": true + }, + "exiftool-vendored": { + "optional": true + }, + "sharp": { + "optional": true + } + } + }, + "node_modules/@dicebear/core": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/core/-/core-5.4.3.tgz", + "integrity": "sha512-qOOlqdVD1CWT0VFxABADP62oPF8WosfE+OkREYD+vZ3T7rq8kauHAUbGkvwRoB60uMld7kfZzEJNhjR7QI22IQ==", + "license": "MIT", + "dependencies": { + "@dicebear/converter": "5.4.3" + }, + "engines": { + "node": "^14.13.1 || >=16.0.0" + } + }, + "node_modules/@dicebear/croodles": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/croodles/-/croodles-5.4.3.tgz", + "integrity": "sha512-eP+BwAb7Pm8msS+hcIMyfleBYSqGngt2Ocu/cNqZV2kSLkfIOrogSb4VJTkVtwbJd2Gpt41d+AxW71QSLN2ARQ==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/croodles-neutral": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/croodles-neutral/-/croodles-neutral-5.4.3.tgz", + "integrity": "sha512-Z4wGeeUEdZjer6xKy5jimgDXQtUnW1OKQuV+LjA6bgyLTB/QmtmspZHzqCOgwZFQAydqcUoxEFWmrIpwNLujBA==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/fun-emoji": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/fun-emoji/-/fun-emoji-5.4.3.tgz", + "integrity": "sha512-La4XonWV0abaIiE4Dj0OOtH7tH5VC1tiXmcapJJ69d3y6YfJnedyhHzD+Xk2gnWFD/X0mnmLJua++BGSrv7YkQ==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/icons": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/icons/-/icons-5.4.3.tgz", + "integrity": "sha512-p173l+PkZBrVtUTgSFVD9dHLc9djkRtxp+tLNsGYkBjeeWmJ/kxtPH5iG7MOp1pUnCHRkWJrLyysV51sgcrNug==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/identicon": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/identicon/-/identicon-5.4.3.tgz", + "integrity": "sha512-it9tHCJ9UWdSwDzbYZVDhx8mZMQKeKXIWzmOWwS/aGHM3aONn8Kjxd6m5rnQGWFVzxxUjedrIOZxFhWuogzYOw==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/initials": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/initials/-/initials-5.4.3.tgz", + "integrity": "sha512-SkCxoo+llqJoOXQsVoJvruQhN4QCLOOtBvNsg7aO0W0MIYPWkJoGkpzKhXVuRBEsmI/QOBfkLMBFBpiHz22n4w==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/lorelei": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/lorelei/-/lorelei-5.4.3.tgz", + "integrity": "sha512-/Zn8lzt0ZCc/S2iPfrSbHqJLa6wh5AoB5S9LclhOmksZqU7RLcjF86wyrwcbg/QZFxMSxvPr8ihL7SbkbRHh3g==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/lorelei-neutral": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/lorelei-neutral/-/lorelei-neutral-5.4.3.tgz", + "integrity": "sha512-eJdnpIAUPXfYiXr+9Kt4r8dDKGiDKc3SliXcqwcEiHnM54k6p6EnAM54SxbxgVsGfKfhB4RxZo2CX1CiENwxUA==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/micah": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/micah/-/micah-5.4.3.tgz", + "integrity": "sha512-2seJqhL2a/AV233nPVuFkY7IBW9EUjB+eRYQTYHqkOfgbnExtS7t7jjC57Ot7+FHvvrMjH43r96CKBvMWHKfJw==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/miniavs": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/miniavs/-/miniavs-5.4.3.tgz", + "integrity": "sha512-+L3YCUuqf1ufPbAMgVGAXPGT81a+4gPJKPn3mqYSpBY6l4xUUku8MPg0K3JDU1T/801ABT4VXkcIlHwgEz2HIg==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/open-peeps": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/open-peeps/-/open-peeps-5.4.3.tgz", + "integrity": "sha512-Xp/7uJBv+iCLG06e7+8KOVI7uDjk5YVj0cZpa6O+03kRF2sdglG8SBKPdT+l5iIxhAK0Yth4vzZZpjsiEqD+Jg==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/personas": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/personas/-/personas-5.4.3.tgz", + "integrity": "sha512-Anb1ICUcA/inrGV3FxGV9KJhsOLegpFo5VOWqyqZ/EbpVf77rgNZCj7GfwyzWuSYMKsnURpbxdTVlCn2LigHeA==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/pixel-art": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/pixel-art/-/pixel-art-5.4.3.tgz", + "integrity": "sha512-itCXZoH5jiVq+yhRMlWyol1TiVJgx/mlZZFcEmIO2tye1QSRWG9fhC4OGln7uvQ8GpLx1cRcVBdHVFA83nuYkQ==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/pixel-art-neutral": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/pixel-art-neutral/-/pixel-art-neutral-5.4.3.tgz", + "integrity": "sha512-giztLosESV1u7Slkl+B/wLSuWTAvhXvVHHmvbM+jouWTM2prKlI+pyrO/02bRl4rXcW49OHmUVIZLyBFZXpaWA==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/shapes": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/shapes/-/shapes-5.4.3.tgz", + "integrity": "sha512-42l2bpAufWkoqW1qzj0A4s5vwqoEtTUfjAl5/WrqNiN9EUFIG05dz5po8CWVe7rmUBuwwRKxhj9zZ7yArtQQ6Q==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@dicebear/thumbs": { + "version": "5.4.3", + "resolved": "https://registry.npmjs.org/@dicebear/thumbs/-/thumbs-5.4.3.tgz", + "integrity": "sha512-9R8MbVkRsOXPJK4+YZ8hx8WqAPls4Ngf1ol1AQvtsU3qXs4hgTsR9Wz2h9pf+IU3dV4JaF53ubGrxWdncKYZig==", + "license": "MIT", + "engines": { + "node": "^14.13.1 || >=16.0.0" + }, + "peerDependencies": { + "@dicebear/core": "^5.0.0" + } + }, + "node_modules/@digitalbazaar/bitstring": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/@digitalbazaar/bitstring/-/bitstring-3.1.0.tgz", "integrity": "sha512-Cii+Sl++qaexOvv3vchhgZFfSmtHPNIPzGegaq4ffPnflVXFu+V2qrJ17aL2+gfLxrlC/zazZFuAltyKTPq7eg==", @@ -8800,6 +9287,19 @@ "url": "https://github.com/sindresorhus/is?sponsor=1" } }, + "node_modules/@sindresorhus/merge-streams": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-2.3.0.tgz", + "integrity": "sha512-LtoMMhxAlorcGhmFYI+LhPgbPZCkgP6ra1YL604EeF6U98pLlQ3iWIGMdWSC+vWmPBWBNgmDBAhnAobLROJmwg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/@sinonjs/commons": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/@sinonjs/commons/-/commons-3.0.1.tgz", @@ -13603,6 +14103,13 @@ "color-support": "bin.js" } }, + "node_modules/colorette": { + "version": "2.0.20", + "resolved": "https://registry.npmjs.org/colorette/-/colorette-2.0.20.tgz", + "integrity": "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==", + "dev": true, + "license": "MIT" + }, "node_modules/combined-stream": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", @@ -15688,15 +16195,28 @@ "node": ">=6" } }, - "node_modules/err-code": { - "version": "2.0.3", - "resolved": "https://registry.npmjs.org/err-code/-/err-code-2.0.3.tgz", - "integrity": "sha512-2bmlRpNKBxT/CRmPOlyISQpNj+qSeYvcym/uT0Jx2bMOlKLtSy1ZmLuVxSEKKyor/N5yhvp/ZiG1oE3DEYMSFA==", - "license": "MIT" - }, - "node_modules/errno": { - "version": "0.1.8", - "resolved": "https://registry.npmjs.org/errno/-/errno-0.1.8.tgz", + "node_modules/environment": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz", + "integrity": "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/err-code": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/err-code/-/err-code-2.0.3.tgz", + "integrity": "sha512-2bmlRpNKBxT/CRmPOlyISQpNj+qSeYvcym/uT0Jx2bMOlKLtSy1ZmLuVxSEKKyor/N5yhvp/ZiG1oE3DEYMSFA==", + "license": "MIT" + }, + "node_modules/errno": { + "version": "0.1.8", + "resolved": "https://registry.npmjs.org/errno/-/errno-0.1.8.tgz", "integrity": "sha512-dJ6oBr5SQ1VSd9qkk7ByRgb/1SH4JZjCHSW/mr63/QcXO9zLVxvJ6Oy13nio03rxpSnVDDjFor75SjVeZWPW/A==", "dev": true, "license": "MIT", @@ -16431,6 +16951,13 @@ "node": ">=6" } }, + "node_modules/eventemitter3": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.1.tgz", + "integrity": "sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==", + "dev": true, + "license": "MIT" + }, "node_modules/events": { "version": "3.3.0", "resolved": "https://registry.npmjs.org/events/-/events-3.3.0.tgz", @@ -16911,6 +17438,23 @@ "license": "Apache-2.0", "optional": true }, + "node_modules/fast-uri": { + "version": "3.0.6", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.0.6.tgz", + "integrity": "sha512-Atfo14OibSv5wAp4VWNsFYE1AchQRTv9cBGWET4pZWHzYshFSS9NQI6I57rdKn9croWVMbYFbLhJ+yJvmZIIHw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" + }, "node_modules/fastq": { "version": "1.19.1", "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.19.1.tgz", @@ -17437,6 +17981,19 @@ "node": "6.* || 8.* || >= 10.*" } }, + "node_modules/get-east-asian-width": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.3.0.tgz", + "integrity": "sha512-vpeMIQKxczTD/0s2CdEWHcb0eeJe6TFjxb+J5xgX7hScxqrGuyjmv4c1D4A/gelKfyox0gJJwIHF+fLjeaM8kQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/get-intrinsic": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz", @@ -17774,6 +18331,26 @@ "node": "*" } }, + "node_modules/global-dirs": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/global-dirs/-/global-dirs-0.1.1.tgz", + "integrity": "sha512-NknMLn7F2J7aflwFOlGdNIuCDpN3VGoSoB+aap3KABFWbHVn1TCgFC+np23J8W2BiZbjfEw3BFBycSMv1AFblg==", + "dev": true, + "license": "MIT", + "dependencies": { + "ini": "^1.3.4" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/global-dirs/node_modules/ini": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz", + "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", + "dev": true, + "license": "ISC" + }, "node_modules/globals": { "version": "13.24.0", "resolved": "https://registry.npmjs.org/globals/-/globals-13.24.0.tgz", @@ -18160,6 +18737,22 @@ "ms": "^2.0.0" } }, + "node_modules/husky": { + "version": "9.1.7", + "resolved": "https://registry.npmjs.org/husky/-/husky-9.1.7.tgz", + "integrity": "sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA==", + "dev": true, + "license": "MIT", + "bin": { + "husky": "bin.js" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/typicode" + } + }, "node_modules/iconv-corefoundation": { "version": "1.1.7", "resolved": "https://registry.npmjs.org/iconv-corefoundation/-/iconv-corefoundation-1.1.7.tgz", @@ -20703,59 +21296,429 @@ "node": ">= 12.0.0" }, "funding": { - "type": "opencollective", - "url": "https://opencollective.com/parcel" + "type": "opencollective", + "url": "https://opencollective.com/parcel" + } + }, + "node_modules/lightningcss/node_modules/detect-libc": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-1.0.3.tgz", + "integrity": "sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==", + "license": "Apache-2.0", + "optional": true, + "peer": true, + "bin": { + "detect-libc": "bin/detect-libc.js" + }, + "engines": { + "node": ">=0.10" + } + }, + "node_modules/lil-gui": { + "version": "0.17.0", + "resolved": "https://registry.npmjs.org/lil-gui/-/lil-gui-0.17.0.tgz", + "integrity": "sha512-MVBHmgY+uEbmJNApAaPbtvNh1RCAeMnKym82SBjtp5rODTYKWtM+MXHCifLe2H2Ti1HuBGBtK/5SyG4ShQ3pUQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/lilconfig": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz", + "integrity": "sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/antonk52" + } + }, + "node_modules/lines-and-columns": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", + "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", + "devOptional": true, + "license": "MIT" + }, + "node_modules/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "uc.micro": "^2.0.0" + } + }, + "node_modules/lint-staged": { + "version": "15.5.2", + "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-15.5.2.tgz", + "integrity": "sha512-YUSOLq9VeRNAo/CTaVmhGDKG+LBtA8KF1X4K5+ykMSwWST1vDxJRB2kv2COgLb1fvpCo+A/y9A0G0znNVmdx4w==", + "dev": true, + "license": "MIT", + "dependencies": { + "chalk": "^5.4.1", + "commander": "^13.1.0", + "debug": "^4.4.0", + "execa": "^8.0.1", + "lilconfig": "^3.1.3", + "listr2": "^8.2.5", + "micromatch": "^4.0.8", + "pidtree": "^0.6.0", + "string-argv": "^0.3.2", + "yaml": "^2.7.0" + }, + "bin": { + "lint-staged": "bin/lint-staged.js" + }, + "engines": { + "node": ">=18.12.0" + }, + "funding": { + "url": "https://opencollective.com/lint-staged" + } + }, + "node_modules/lint-staged/node_modules/chalk": { + "version": "5.6.0", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.0.tgz", + "integrity": "sha512-46QrSQFyVSEyYAgQ22hQ+zDa60YHA4fBstHmtSApj1Y5vKtG27fWowW03jCk5KcbXEWPZUIR894aARCA/G1kfQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.17.0 || ^14.13 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/chalk/chalk?sponsor=1" + } + }, + "node_modules/lint-staged/node_modules/commander": { + "version": "13.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-13.1.0.tgz", + "integrity": "sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/lint-staged/node_modules/debug": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz", + "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/lint-staged/node_modules/execa": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/execa/-/execa-8.0.1.tgz", + "integrity": "sha512-VyhnebXciFV2DESc+p6B+y0LjSm0krU4OgJN44qFAhBY0TJ+1V61tYD2+wHusZ6F9n5K+vl8k0sTy7PEfV4qpg==", + "dev": true, + "license": "MIT", + "dependencies": { + "cross-spawn": "^7.0.3", + "get-stream": "^8.0.1", + "human-signals": "^5.0.0", + "is-stream": "^3.0.0", + "merge-stream": "^2.0.0", + "npm-run-path": "^5.1.0", + "onetime": "^6.0.0", + "signal-exit": "^4.1.0", + "strip-final-newline": "^3.0.0" + }, + "engines": { + "node": ">=16.17" + }, + "funding": { + "url": "https://github.com/sindresorhus/execa?sponsor=1" + } + }, + "node_modules/lint-staged/node_modules/get-stream": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-8.0.1.tgz", + "integrity": "sha512-VaUJspBffn/LMCJVoMvSAdmscJyS1auj5Zulnn5UoYcY531UWmdwhRWkcGKnGU93m5HSXP9LP2usOryrBtQowA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lint-staged/node_modules/human-signals": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-5.0.0.tgz", + "integrity": "sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=16.17.0" + } + }, + "node_modules/lint-staged/node_modules/is-stream": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-3.0.0.tgz", + "integrity": "sha512-LnQR4bZ9IADDRSkvpqMGvt/tEJWclzklNgSw48V5EAaAeDd6qGvN8ei6k5p0tvxSR171VmGyHuTiAOfxAbr8kA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lint-staged/node_modules/mimic-fn": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-4.0.0.tgz", + "integrity": "sha512-vqiC06CuhBTUdZH+RYl8sFrL096vA45Ok5ISO6sE/Mr1jRbGH4Csnhi8f3wKVl7x8mO4Au7Ir9D3Oyv1VYMFJw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lint-staged/node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/lint-staged/node_modules/npm-run-path": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-5.3.0.tgz", + "integrity": "sha512-ppwTtiJZq0O/ai0z7yfudtBpWIoxM8yE6nHi1X47eFR2EWORqfbu6CnPlNsjeN683eT0qG6H/Pyf9fCcvjnnnQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-key": "^4.0.0" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lint-staged/node_modules/onetime": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/onetime/-/onetime-6.0.0.tgz", + "integrity": "sha512-1FlR+gjXK7X+AsAHso35MnyN5KqGwJRi/31ft6x0M194ht7S+rWAvd7PHss9xSKMzE0asv1pyIHaJYq+BbacAQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "mimic-fn": "^4.0.0" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lint-staged/node_modules/path-key": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-4.0.0.tgz", + "integrity": "sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/lint-staged/node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/lint-staged/node_modules/strip-final-newline": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-3.0.0.tgz", + "integrity": "sha512-dOESqjYr96iWYylGObzd39EuNTa5VJxyvVAEm5Jnh7KGo75V43Hk1odPQkNDyXNmUR6k+gEiDVXnjB8HJ3crXw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/listr2": { + "version": "8.3.3", + "resolved": "https://registry.npmjs.org/listr2/-/listr2-8.3.3.tgz", + "integrity": "sha512-LWzX2KsqcB1wqQ4AHgYb4RsDXauQiqhjLk+6hjbaeHG4zpjjVAB6wC/gz6X0l+Du1cN3pUB5ZlrvTbhGSNnUQQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "cli-truncate": "^4.0.0", + "colorette": "^2.0.20", + "eventemitter3": "^5.0.1", + "log-update": "^6.1.0", + "rfdc": "^1.4.1", + "wrap-ansi": "^9.0.0" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/listr2/node_modules/ansi-regex": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.0.tgz", + "integrity": "sha512-TKY5pyBkHyADOPYlRT9Lx6F544mPl0vS5Ew7BJ45hA08Q+t3GjbueLliBWN3sMICk6+y7HdyxSzC4bWS8baBdg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/listr2/node_modules/ansi-styles": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.1.tgz", + "integrity": "sha512-bN798gFfQX+viw3R7yrGWRqnrN2oRkEkUjjl4JNn4E8GxxbjtG3FbrEIIY3l8/hrwUwIeCZvi4QuOTP4MErVug==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/listr2/node_modules/cli-truncate": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/cli-truncate/-/cli-truncate-4.0.0.tgz", + "integrity": "sha512-nPdaFdQ0h/GEigbPClz11D0v/ZJEwxmeVZGeMo3Z5StPtUTkA9o1lD6QwoirYiSDzbcwn2XcjwmCp68W1IS4TA==", + "dev": true, + "license": "MIT", + "dependencies": { + "slice-ansi": "^5.0.0", + "string-width": "^7.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/listr2/node_modules/emoji-regex": { + "version": "10.4.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.4.0.tgz", + "integrity": "sha512-EC+0oUMY1Rqm4O6LLrgjtYDvcVYTy7chDnM4Q7030tP4Kwj3u/pR6gP9ygnp2CJMK5Gq+9Q2oqmrFJAz01DXjw==", + "dev": true, + "license": "MIT" + }, + "node_modules/listr2/node_modules/is-fullwidth-code-point": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-4.0.0.tgz", + "integrity": "sha512-O4L094N2/dZ7xqVdrXhh9r1KODPJpFms8B5sGdJLPy664AgvXsreZUyCQQNItZRDlYug4xStLjNp/sz3HvBowQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/listr2/node_modules/slice-ansi": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-5.0.0.tgz", + "integrity": "sha512-FC+lgizVPfie0kkhqUScwRu1O/lF6NOgJmlCgK+/LYxDCTk8sGelYaHDhFcDN+Sn3Cv+3VSa4Byeo+IMCzpMgQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.0.0", + "is-fullwidth-code-point": "^4.0.0" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/slice-ansi?sponsor=1" } }, - "node_modules/lightningcss/node_modules/detect-libc": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-1.0.3.tgz", - "integrity": "sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==", - "license": "Apache-2.0", - "optional": true, - "peer": true, - "bin": { - "detect-libc": "bin/detect-libc.js" + "node_modules/listr2/node_modules/string-width": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz", + "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^10.3.0", + "get-east-asian-width": "^1.0.0", + "strip-ansi": "^7.1.0" }, "engines": { - "node": ">=0.10" + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" } }, - "node_modules/lil-gui": { - "version": "0.17.0", - "resolved": "https://registry.npmjs.org/lil-gui/-/lil-gui-0.17.0.tgz", - "integrity": "sha512-MVBHmgY+uEbmJNApAaPbtvNh1RCAeMnKym82SBjtp5rODTYKWtM+MXHCifLe2H2Ti1HuBGBtK/5SyG4ShQ3pUQ==", - "dev": true, - "license": "MIT" - }, - "node_modules/lilconfig": { - "version": "3.1.3", - "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz", - "integrity": "sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==", + "node_modules/listr2/node_modules/strip-ansi": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.0.tgz", + "integrity": "sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ==", "dev": true, "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, "engines": { - "node": ">=14" + "node": ">=12" }, "funding": { - "url": "https://github.com/sponsors/antonk52" + "url": "https://github.com/chalk/strip-ansi?sponsor=1" } }, - "node_modules/lines-and-columns": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz", - "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==", - "devOptional": true, - "license": "MIT" - }, - "node_modules/linkify-it": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", - "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "node_modules/listr2/node_modules/wrap-ansi": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.0.tgz", + "integrity": "sha512-G8ura3S+3Z2G+mkgNRq8dqaFZAuxfsxpBB8OCTGRTCtp+l/v9nbFNmCUP1BZMts3G1142MsZfn6eeUKrr4PD1Q==", "dev": true, "license": "MIT", "dependencies": { - "uc.micro": "^2.0.0" + "ansi-styles": "^6.2.1", + "string-width": "^7.0.0", + "strip-ansi": "^7.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" } }, "node_modules/load-json-file": { @@ -20864,6 +21827,13 @@ "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", "license": "MIT" }, + "node_modules/lodash.camelcase": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/lodash.camelcase/-/lodash.camelcase-4.3.0.tgz", + "integrity": "sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==", + "dev": true, + "license": "MIT" + }, "node_modules/lodash.clonedeep": { "version": "4.5.0", "resolved": "https://registry.npmjs.org/lodash.clonedeep/-/lodash.clonedeep-4.5.0.tgz", @@ -20892,6 +21862,13 @@ "deprecated": "This package is deprecated. Use require('node:util').isDeepStrictEqual instead.", "license": "MIT" }, + "node_modules/lodash.isfunction": { + "version": "3.0.9", + "resolved": "https://registry.npmjs.org/lodash.isfunction/-/lodash.isfunction-3.0.9.tgz", + "integrity": "sha512-AirXNj15uRIMMPihnkInB4i3NHeb4iBtNg9WRWuK2o31S+ePwwNmDPaTL3o7dTJ+VXNZim7rFs4rxN4YU1oUJw==", + "dev": true, + "license": "MIT" + }, "node_modules/lodash.ismatch": { "version": "4.4.0", "resolved": "https://registry.npmjs.org/lodash.ismatch/-/lodash.ismatch-4.4.0.tgz", @@ -20899,6 +21876,20 @@ "dev": true, "license": "MIT" }, + "node_modules/lodash.isplainobject": { + "version": "4.0.6", + "resolved": "https://registry.npmjs.org/lodash.isplainobject/-/lodash.isplainobject-4.0.6.tgz", + "integrity": "sha512-oSXzaWypCMHkPC3NvBEaPHf0KsA5mvPrOPgQWDsbg8n7orZ290M0BmC/jgRZ4vcJ6DTAhjrsSYgdsW/F+MFOBA==", + "dev": true, + "license": "MIT" + }, + "node_modules/lodash.kebabcase": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/lodash.kebabcase/-/lodash.kebabcase-4.1.1.tgz", + "integrity": "sha512-N8XRTIMMqqDgSy4VLKPnJ/+hpGZN+PHQiJnSenYqPaVV/NCqEogTnAdZLQiGKhxX+JCs8waWq2t1XHWKOmlY8g==", + "dev": true, + "license": "MIT" + }, "node_modules/lodash.memoize": { "version": "4.1.2", "resolved": "https://registry.npmjs.org/lodash.memoize/-/lodash.memoize-4.1.2.tgz", @@ -20913,6 +21904,27 @@ "dev": true, "license": "MIT" }, + "node_modules/lodash.mergewith": { + "version": "4.6.2", + "resolved": "https://registry.npmjs.org/lodash.mergewith/-/lodash.mergewith-4.6.2.tgz", + "integrity": "sha512-GK3g5RPZWTRSeLSpgP8Xhra+pnjBC56q9FZYe1d5RN3TJ35dbkGy3YqBSMbyCrlbi+CM9Z3Jk5yTL7RCsqboyQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/lodash.snakecase": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/lodash.snakecase/-/lodash.snakecase-4.1.1.tgz", + "integrity": "sha512-QZ1d4xoBHYUeuouhEq3lk3Uq7ldgyFXGBhg04+oRLnIz8o9T65Eh+8YdroUwn846zchkA9yDsDl5CVVaV2nqYw==", + "dev": true, + "license": "MIT" + }, + "node_modules/lodash.startcase": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/lodash.startcase/-/lodash.startcase-4.4.0.tgz", + "integrity": "sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==", + "dev": true, + "license": "MIT" + }, "node_modules/lodash.throttle": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/lodash.throttle/-/lodash.throttle-4.1.1.tgz", @@ -20921,20 +21933,250 @@ "optional": true, "peer": true }, - "node_modules/log-symbols": { - "version": "4.1.0", - "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-4.1.0.tgz", - "integrity": "sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==", + "node_modules/lodash.uniq": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/lodash.uniq/-/lodash.uniq-4.5.0.tgz", + "integrity": "sha512-xfBaXQd9ryd9dlSDvnvI0lvxfLJlYAZzXomUYzLKtUeOQvOP5piqAWuGtrhWeqaXK9hhoM/iyJc5AV+XfsX3HQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/lodash.upperfirst": { + "version": "4.3.1", + "resolved": "https://registry.npmjs.org/lodash.upperfirst/-/lodash.upperfirst-4.3.1.tgz", + "integrity": "sha512-sReKOYJIJf74dhJONhU4e0/shzi1trVbSWDOhKYE5XV2O+H7Sb2Dihwuc7xWxVl+DgFPyTqIN3zMfT9cq5iWDg==", + "dev": true, + "license": "MIT" + }, + "node_modules/log-symbols": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-4.1.0.tgz", + "integrity": "sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==", + "license": "MIT", + "dependencies": { + "chalk": "^4.1.0", + "is-unicode-supported": "^0.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/log-update/-/log-update-6.1.0.tgz", + "integrity": "sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-escapes": "^7.0.0", + "cli-cursor": "^5.0.0", + "slice-ansi": "^7.1.0", + "strip-ansi": "^7.1.0", + "wrap-ansi": "^9.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/ansi-escapes": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-7.0.0.tgz", + "integrity": "sha512-GdYO7a61mR0fOlAsvC9/rIHf7L96sBc6dEWzeOu+KAea5bZyQRPIpojrVoI4AXGJS/ycu/fBTdLrUkA4ODrvjw==", + "dev": true, + "license": "MIT", + "dependencies": { + "environment": "^1.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/ansi-regex": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.0.tgz", + "integrity": "sha512-TKY5pyBkHyADOPYlRT9Lx6F544mPl0vS5Ew7BJ45hA08Q+t3GjbueLliBWN3sMICk6+y7HdyxSzC4bWS8baBdg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-regex?sponsor=1" + } + }, + "node_modules/log-update/node_modules/ansi-styles": { + "version": "6.2.1", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.1.tgz", + "integrity": "sha512-bN798gFfQX+viw3R7yrGWRqnrN2oRkEkUjjl4JNn4E8GxxbjtG3FbrEIIY3l8/hrwUwIeCZvi4QuOTP4MErVug==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/log-update/node_modules/cli-cursor": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz", + "integrity": "sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==", + "dev": true, + "license": "MIT", + "dependencies": { + "restore-cursor": "^5.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/emoji-regex": { + "version": "10.4.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.4.0.tgz", + "integrity": "sha512-EC+0oUMY1Rqm4O6LLrgjtYDvcVYTy7chDnM4Q7030tP4Kwj3u/pR6gP9ygnp2CJMK5Gq+9Q2oqmrFJAz01DXjw==", + "dev": true, + "license": "MIT" + }, + "node_modules/log-update/node_modules/is-fullwidth-code-point": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-5.0.0.tgz", + "integrity": "sha512-OVa3u9kkBbw7b8Xw5F9P+D/T9X+Z4+JruYVNapTjPYZYUznQ5YfWeFkOj606XYYW8yugTfC8Pj0hYqvi4ryAhA==", + "dev": true, + "license": "MIT", + "dependencies": { + "get-east-asian-width": "^1.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/onetime": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/onetime/-/onetime-7.0.0.tgz", + "integrity": "sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "mimic-function": "^5.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/restore-cursor": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-5.1.0.tgz", + "integrity": "sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==", + "dev": true, + "license": "MIT", + "dependencies": { + "onetime": "^7.0.0", + "signal-exit": "^4.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/log-update/node_modules/slice-ansi": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-7.1.0.tgz", + "integrity": "sha512-bSiSngZ/jWeX93BqeIAbImyTbEihizcwNjFoRUIY/T1wWQsfsm2Vw1agPKylXvQTU7iASGdHhyqRlqQzfz+Htg==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-styles": "^6.2.1", + "is-fullwidth-code-point": "^5.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/slice-ansi?sponsor=1" + } + }, + "node_modules/log-update/node_modules/string-width": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz", + "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex": "^10.3.0", + "get-east-asian-width": "^1.0.0", + "strip-ansi": "^7.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/log-update/node_modules/strip-ansi": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.0.tgz", + "integrity": "sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^6.0.1" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/chalk/strip-ansi?sponsor=1" + } + }, + "node_modules/log-update/node_modules/wrap-ansi": { + "version": "9.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.0.tgz", + "integrity": "sha512-G8ura3S+3Z2G+mkgNRq8dqaFZAuxfsxpBB8OCTGRTCtp+l/v9nbFNmCUP1BZMts3G1142MsZfn6eeUKrr4PD1Q==", + "dev": true, "license": "MIT", "dependencies": { - "chalk": "^4.1.0", - "is-unicode-supported": "^0.1.0" + "ansi-styles": "^6.2.1", + "string-width": "^7.0.0", + "strip-ansi": "^7.1.0" }, "engines": { - "node": ">=10" + "node": ">=18" }, "funding": { - "url": "https://github.com/sponsors/sindresorhus" + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" } }, "node_modules/loose-envify": { @@ -21245,6 +22487,250 @@ "node": ">=16 || 14 >=14.17" } }, + "node_modules/markdownlint-cli2": { + "version": "0.18.1", + "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.18.1.tgz", + "integrity": "sha512-/4Osri9QFGCZOCTkfA8qJF+XGjKYERSHkXzxSyS1hd3ZERJGjvsUao2h4wdnvpHp6Tu2Jh/bPHM0FE9JJza6ng==", + "dev": true, + "license": "MIT", + "dependencies": { + "globby": "14.1.0", + "js-yaml": "4.1.0", + "jsonc-parser": "3.3.1", + "markdown-it": "14.1.0", + "markdownlint": "0.38.0", + "markdownlint-cli2-formatter-default": "0.0.5", + "micromatch": "4.0.8" + }, + "bin": { + "markdownlint-cli2": "markdownlint-cli2-bin.mjs" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + } + }, + "node_modules/markdownlint-cli2-formatter-default": { + "version": "0.0.5", + "resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.5.tgz", + "integrity": "sha512-4XKTwQ5m1+Txo2kuQ3Jgpo/KmnG+X90dWt4acufg6HVGadTUG5hzHF/wssp9b5MBYOMCnZ9RMPaU//uHsszF8Q==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + }, + "peerDependencies": { + "markdownlint-cli2": ">=0.0.4" + } + }, + "node_modules/markdownlint-cli2/node_modules/globby": { + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-14.1.0.tgz", + "integrity": "sha512-0Ia46fDOaT7k4og1PDW4YbodWWr3scS2vAr2lTbsplOt2WkKp0vQbkI9wKis/T5LV/dqPjO3bpS/z6GTJB82LA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@sindresorhus/merge-streams": "^2.1.0", + "fast-glob": "^3.3.3", + "ignore": "^7.0.3", + "path-type": "^6.0.0", + "slash": "^5.1.0", + "unicorn-magic": "^0.3.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/markdownlint-cli2/node_modules/ignore": { + "version": "7.0.5", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz", + "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/markdownlint-cli2/node_modules/markdownlint": { + "version": "0.38.0", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.38.0.tgz", + "integrity": "sha512-xaSxkaU7wY/0852zGApM8LdlIfGCW8ETZ0Rr62IQtAnUMlMuifsg09vWJcNYeL4f0anvr8Vo4ZQar8jGpV0btQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "micromark": "4.0.2", + "micromark-core-commonmark": "2.0.3", + "micromark-extension-directive": "4.0.0", + "micromark-extension-gfm-autolink-literal": "2.1.0", + "micromark-extension-gfm-footnote": "2.1.0", + "micromark-extension-gfm-table": "2.1.1", + "micromark-extension-math": "3.1.0", + "micromark-util-types": "2.0.2" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/DavidAnson" + } + }, + "node_modules/markdownlint-cli2/node_modules/micromark": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz", + "integrity": "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-core-commonmark": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-combine-extensions": "^2.0.0", + "micromark-util-decode-numeric-character-reference": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/markdownlint-cli2/node_modules/micromark-core-commonmark": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.3.tgz", + "integrity": "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "devlop": "^1.0.0", + "micromark-factory-destination": "^2.0.0", + "micromark-factory-label": "^2.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-title": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-chunked": "^2.0.0", + "micromark-util-classify-character": "^2.0.0", + "micromark-util-html-tag-name": "^2.0.0", + "micromark-util-normalize-identifier": "^2.0.0", + "micromark-util-resolve-all": "^2.0.0", + "micromark-util-subtokenize": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/markdownlint-cli2/node_modules/micromark-extension-directive": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/micromark-extension-directive/-/micromark-extension-directive-4.0.0.tgz", + "integrity": "sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-factory-whitespace": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0", + "parse-entities": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/markdownlint-cli2/node_modules/micromark-extension-gfm-table": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz", + "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==", + "dev": true, + "license": "MIT", + "dependencies": { + "devlop": "^1.0.0", + "micromark-factory-space": "^2.0.0", + "micromark-util-character": "^2.0.0", + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/markdownlint-cli2/node_modules/micromark-util-types": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz", + "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/markdownlint-cli2/node_modules/path-type": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-6.0.0.tgz", + "integrity": "sha512-Vj7sf++t5pBD637NSfkxpHSMfWaeig5+DKWLhcqIYx6mWQz5hdJTGDVMQiJcw1ZYkhs7AazKDGpRVji1LJCZUQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/markdownlint-cli2/node_modules/slash": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz", + "integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=14.16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/marky": { "version": "1.3.0", "resolved": "https://registry.npmjs.org/marky/-/marky-1.3.0.tgz", @@ -22973,6 +24459,19 @@ "node": ">=6" } }, + "node_modules/mimic-function": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/mimic-function/-/mimic-function-5.0.1.tgz", + "integrity": "sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/mimic-response": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-1.0.1.tgz", @@ -24528,6 +26027,19 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/pidtree": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/pidtree/-/pidtree-0.6.0.tgz", + "integrity": "sha512-eG2dWTVw5bzqGRztnHExczNxt5VGsE6OwTeCG3fdUf9KBsZzO3R5OIIIzWR+iZA0NtZ+RDVdaoE2dK1cn6jH4g==", + "dev": true, + "license": "MIT", + "bin": { + "pidtree": "bin/pidtree.js" + }, + "engines": { + "node": ">=0.10" + } + }, "node_modules/pify": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/pify/-/pify-2.3.0.tgz", @@ -26915,9 +28427,8 @@ "version": "2.0.2", "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "devOptional": true, "license": "MIT", - "optional": true, - "peer": true, "engines": { "node": ">=0.10.0" } @@ -27031,6 +28542,19 @@ "node": ">=4" } }, + "node_modules/resolve-global": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/resolve-global/-/resolve-global-1.0.0.tgz", + "integrity": "sha512-zFa12V4OLtT5XUX/Q4VLvTfBf+Ok0SPc1FNGM/z9ctUdiU618qwKpWnd0CHs3+RqROfyEg/DhuHbMWYqcgljEw==", + "dev": true, + "license": "MIT", + "dependencies": { + "global-dirs": "^0.1.1" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/resolve-pkg-maps": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz", @@ -27105,6 +28629,13 @@ "node": ">=0.10.0" } }, + "node_modules/rfdc": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz", + "integrity": "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==", + "dev": true, + "license": "MIT" + }, "node_modules/rimraf": { "version": "6.0.1", "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-6.0.1.tgz", @@ -28488,6 +30019,16 @@ "safe-buffer": "~5.2.0" } }, + "node_modules/string-argv": { + "version": "0.3.2", + "resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.2.tgz", + "integrity": "sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.6.19" + } + }, "node_modules/string-length": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/string-length/-/string-length-4.0.2.tgz", @@ -29976,6 +31517,19 @@ "node": ">=4" } }, + "node_modules/unicorn-magic": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.3.0.tgz", + "integrity": "sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/unique-filename": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/unique-filename/-/unique-filename-2.0.1.tgz", diff --git a/package.json b/package.json index 1eee0271..c756dacb 100644 --- a/package.json +++ b/package.json @@ -99,8 +99,8 @@ "build:electron:dmg:dev": "./scripts/build-electron.sh --dev --dmg", "build:electron:dmg:test": "./scripts/build-electron.sh --test --dmg", "build:electron:dmg:prod": "./scripts/build-electron.sh --prod --dmg", - "markdown:fix": "./scripts/fix-markdown.sh", - "markdown:check": "./scripts/validate-markdown.sh", + "markdown:fix": "markdownlint-cli2 --fix", + "markdown:check": "markdownlint-cli2", "markdown:setup": "./scripts/setup-markdown-hooks.sh", "prepare": "husky", "guard": "bash ./scripts/build-arch-guard.sh", @@ -133,10 +133,13 @@ "build:android:test:run:custom": "./scripts/build-android.sh --test --api-ip --auto-run" }, "lint-staged": { - "*.{js,ts,vue,css,md,json,yml,yaml}": "eslint --fix || true" + "*.{js,ts,vue,css,json,yml,yaml}": "eslint --fix || true", + "*.{md,markdown,mdc}": "markdownlint-cli2 --fix" }, - "commitlint": { - "extends": ["@commitlint/config-conventional"] + "commitlint": { + "extends": [ + "@commitlint/config-conventional" + ] }, "dependencies": { "@capacitor-community/electron": "^5.0.1", @@ -227,6 +230,8 @@ }, "devDependencies": { "@capacitor/assets": "^3.0.5", + "@commitlint/cli": "^18.6.1", + "@commitlint/config-conventional": "^18.6.2", "@playwright/test": "^1.54.2", "@types/dom-webcodecs": "^0.1.7", "@types/jest": "^30.0.0", @@ -254,13 +259,12 @@ "eslint-plugin-prettier": "^5.2.1", "eslint-plugin-vue": "^9.32.0", "fs-extra": "^11.3.0", + "husky": "^9.0.11", "jest": "^30.0.4", + "lint-staged": "^15.2.2", "markdownlint": "^0.37.4", "markdownlint-cli": "^0.44.0", - "husky": "^9.0.11", - "lint-staged": "^15.2.2", - "@commitlint/cli": "^18.6.1", - "@commitlint/config-conventional": "^18.6.2", + "markdownlint-cli2": "^0.18.1", "npm-check-updates": "^17.1.13", "path-browserify": "^1.0.1", "postcss": "^8.4.38",