diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md new file mode 100644 index 00000000..f28acf01 --- /dev/null +++ b/.cursor/rules/README.md @@ -0,0 +1,151 @@ +# .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 +- **`meta_rule_usage_guide.md`** - How to use meta-rules in practice + +### **`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_documentation.mdc`** - Documentation writing and education workflow +- **`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 + - **Documentation**: Use `meta_documentation.mdc` for all documentation work + - **Getting Started**: See `docs/meta_rule_usage_guide.md` for comprehensive usage instructions +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 +8. **Educational focus** - Documentation emphasizes human competence over technical description + +## 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 ccc37996..ad8a2249 100644 --- a/.cursor/rules/app/timesafari.mdc +++ b/.cursor/rules/app/timesafari.mdc @@ -1,3 +1,6 @@ +--- +alwaysApply: false +--- # Time Safari Context **Author**: Matthew Raymer @@ -15,10 +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. @@ -27,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 @@ -57,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 @@ -80,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 651a12d5..1b07690b 100644 --- a/.cursor/rules/architecture/build_architecture_guard.mdc +++ b/.cursor/rules/architecture/build_architecture_guard.mdc @@ -1,13 +1,8 @@ ---- -description: Guards against unauthorized changes to the TimeSafari building - architecture -alwaysApply: false ---- # Build Architecture Guard Directive **Author**: Matthew Raymer -**Date**: 2025-08-20 +**Date**: 2025-08-22 **Status**: 🎯 **ACTIVE** - Build system protection guidelines ## Purpose @@ -17,24 +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. + ## 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 + +- **Resource Generation**: `capacitor-assets` integration and verification + +- **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 + ### 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 @@ -42,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 @@ -51,17 +82,33 @@ 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 + +- **Asset regeneration logic**: Automatic fallback for missing Android resources + **Process**: Code review + platform testing + documentation update ### 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 @@ -71,225 +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 - -### 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` - -### 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 - -## 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 - -**ADR must include**: motivation, alternatives, risks, validation plan, rollback, - doc diffs. - -## Competence Hooks +- **Change** environment configurations -### Why This Works +- **Modify** asset generation scripts -- **Prevents Build Failures**: Catches issues before they reach production -- **Maintains Consistency**: Ensures all platforms build identically -- **Reduces Debugging Time**: Prevents build system regressions +- **Alter** test infrastructure -### Common Pitfalls +- **Update** platform SDK versions -- **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 +**See also**: -- Learn to test build changes across all platforms simultaneously +- `.cursor/rules/architecture/build_validation.mdc` for -### Teach-back + detailed validation procedures -- "What three platforms must I test before committing a build script change?" +- `.cursor/rules/architecture/build_testing.mdc` for testing requirements -## Collaboration Hooks +**Status**: Active build protection guidelines +**Priority**: Critical +**Estimated Effort**: Ongoing reference +**Dependencies**: None +**Stakeholders**: Development team, DevOps team, Build team -### Team Review Requirements +**Estimated Effort**: Ongoing vigilance +**Dependencies**: All build system components +**Stakeholders**: Development team, DevOps, Platform owners +**Next Review**: 2025-09-22 -- **Platform Owners**: iOS, Android, Electron, Web specialists -- **DevOps**: CI/CD pipeline maintainers -- **QA**: Testing infrastructure owners +## Model Implementation Checklist -### Discussion Prompts +### Before Build Changes -- "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?" +- [ ] **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 -## Self-Check (Before Allowing Changes) +### During Build 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? +- [ ] **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-20 +- [ ] **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..4f1da0f4 --- /dev/null +++ b/.cursor/rules/core/harbor_pilot_universal.mdc @@ -0,0 +1,202 @@ +```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..74024bff --- /dev/null +++ b/.cursor/rules/docs/markdown_core.mdc @@ -0,0 +1,210 @@ +# 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. + +**Primary Focus**: Create educational content that increases human +competence, not just technical descriptions. + +## 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 +5. **Educational Value**: Focus on increasing reader competence and + understanding + +### **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 +- ❌ Focus only on technical details without educational context +- ❌ Assume reader has extensive prior knowledge + +### **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 +- ✅ Explain concepts before implementation details +- ✅ Provide context and motivation for technical choices +- ✅ Include examples that illustrate key concepts + +## 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 + +## Educational Content Standards + +### **Content Structure for Learning** + +- **Concept First**: Explain what something is before how to use it +- **Context Matters**: Explain why and when to use a feature +- **Progressive Disclosure**: Start simple, add complexity gradually +- **Real Examples**: Use concrete, relatable scenarios +- **Common Questions**: Anticipate and answer reader questions + +### **Writing for Understanding** + +- **Conversational Tone**: Write as if explaining to a colleague +- **Active Voice**: "You can do this" not "This can be done" +- **Question Format**: "What happens when..." to engage thinking +- **Analogies**: Use familiar concepts to explain complex ideas +- **Limitations**: Clearly state what solutions don't do + +## 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 +- [ ] **Educational Focus**: Plan content structure for learning progression +- [ ] **Audience Consideration**: Identify target reader knowledge level + +### 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 +- [ ] **Educational Review**: Verify content increases reader competence +- [ ] **Example Validation**: Ensure examples illustrate key concepts clearly + +### 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 +- [ ] **Educational Value**: Content increases reader understanding and competence +- [ ] **Context Clarity**: Reader understands when and why to use the information + +--- + +**See also**: + +- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow +- `.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..eacb6720 --- /dev/null +++ b/.cursor/rules/docs/markdown_templates.mdc @@ -0,0 +1,314 @@ +# Markdown Templates & Examples + +> **Agent role**: Reference this file for document templates, structure, +> and examples when creating new documentation. +> +> **Focus**: Create educational content that increases human competence, +> not just technical descriptions. + +## 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. + +**Educational Goal**: What will the reader learn and how will it increase +their competence? + +## Current State + +Description of current situation or problem. + +**Why This Matters**: Explain the business value and user benefit of +addressing this situation. + +## Implementation Plan + +### Phase 1: Foundation + +- [ ] Task 1 +- [ ] Task 2 + +**Learning Context**: What concepts should the reader understand before +proceeding with implementation? + +## Next Steps + +1. **Review and approve plan** +2. **Begin implementation** +3. **Test and validate** + +**Continued Learning**: Where can the reader go next to deepen their +understanding? + +--- + +**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. + +**Business Context**: Why is this specification needed and what problem +does it solve for users? + +## Requirements + +### Functional Requirements + +- [ ] Requirement 1 +- [ ] Requirement 2 + +### Non-Functional Requirements + +- [ ] Performance requirement +- [ ] Security requirement + +## Technical Design + +### Architecture + +Description of the technical architecture. + +**Design Rationale**: Why was this architecture chosen over alternatives? +What are the trade-offs and benefits? + +### 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 + +**Learning from Testing**: What insights does testing provide about the +system's behavior and design? + +--- + +## Educational Documentation Template + +### **Concept Explanation Template** + +```markdown +## What is [Concept Name]? + +Brief, clear definition of the concept. + +## Why Does [Concept Name] Matter? + +Explain the business value and user benefit. + +## How Does [Concept Name] Work? + +High-level explanation of the mechanism. + +## When Would You Use [Concept Name]? + +Real-world scenarios and use cases. + +## Common Misconceptions + +Address typical misunderstandings. + +## Examples + +Concrete examples that illustrate the concept. + +## Next Steps + +Where to learn more about related concepts. +``` + +### **Tutorial Template** + +```markdown +## Learning Objective + +What the reader will accomplish by the end. + +## Prerequisites + +What the reader should know before starting. + +## Step-by-Step Guide + +1. **Step 1**: What to do and why +2. **Step 2**: What to do and why +3. **Step 3**: What to do and why + +## Verification + +How to confirm the tutorial was successful. + +## Troubleshooting + +Common issues and how to resolve them. + +## What You've Learned + +Summary of key concepts and skills. + +## Next Steps + +Where to apply this knowledge next. +``` +- [ ] 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/meta_documentation.mdc` for comprehensive documentation workflow +- `.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/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_documentation.mdc b/.cursor/rules/meta_documentation.mdc new file mode 100644 index 00000000..67e23c0c --- /dev/null +++ b/.cursor/rules/meta_documentation.mdc @@ -0,0 +1,237 @@ +# Meta-Rule: Documentation Writing & Education + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Documentation writing and education workflow + +## Purpose + +This meta-rule bundles documentation-related rules to create comprehensive, +educational documentation that increases human competence rather than just +providing technical descriptions. + +## When to Use + +**Use this meta-rule when**: +- Writing new documentation +- Updating existing documentation +- Creating technical guides +- Writing migration documentation +- Creating architectural documentation +- Writing user guides or tutorials + +## Bundled Rules + +### **Core Documentation Standards** + +- **`docs/markdown_core.mdc`** - Core markdown formatting and automation +- **`docs/markdown_templates.mdc`** - Document templates and structure +- **`docs/markdown_workflow.mdc`** - Documentation validation workflows + +### **Documentation Principles** + +- **`core/base_context.mdc`** - Human competence first principles +- **`core/less_complex.mdc`** - Minimalist solution guidelines +- **`development/software_development.mdc`** - Development documentation standards + +### **Context-Specific Rules** + +- **`app/timesafari.mdc`** - TimeSafari application context +- **`app/timesafari_development.mdc`** - Development documentation patterns +- **`architecture/architectural_patterns.mdc`** - Architecture documentation + +## Core Documentation Philosophy + +### **Education Over Technical Description** + +**Primary Goal**: Increase human competence and understanding +**Secondary Goal**: Provide accurate technical information +**Approach**: Explain the "why" before the "how" + +### **Human Competence Principles** + +1. **Context First**: Explain the problem before the solution +2. **Learning Path**: Structure content for progressive understanding +3. **Real Examples**: Use concrete, relatable examples +4. **Common Pitfalls**: Warn about typical mistakes and misconceptions +5. **Decision Context**: Explain why certain choices were made + +### **Documentation Hierarchy** + +1. **Conceptual Understanding** - What is this and why does it matter? +2. **Context and Motivation** - When and why would you use this? +3. **Technical Implementation** - How do you implement it? +4. **Examples and Patterns** - What does it look like in practice? +5. **Troubleshooting** - What can go wrong and how to fix it? + +## Implementation Guidelines + +### **Document Structure** + +**Mandatory Sections**: +- **Overview**: Clear purpose and scope with educational context +- **Why This Matters**: Business value and user benefit explanation +- **Core Concepts**: Fundamental understanding before implementation +- **Implementation**: Step-by-step technical guidance +- **Examples**: Real-world usage patterns +- **Common Issues**: Troubleshooting and prevention +- **Next Steps**: Where to go from here + +**Optional Sections**: +- **Background**: Historical context and evolution +- **Alternatives**: Other approaches and trade-offs +- **Advanced Topics**: Deep dive into complex scenarios +- **References**: Additional learning resources + +### **Writing Style** + +**Educational Approach**: +- **Conversational tone**: Write as if explaining to a colleague +- **Progressive disclosure**: Start simple, add complexity gradually +- **Active voice**: "You can do this" not "This can be done" +- **Question format**: "What happens when..." to engage thinking +- **Analogies**: Use familiar concepts to explain complex ideas + +**Technical Accuracy**: +- **Precise language**: Use exact technical terms consistently +- **Code examples**: Working, tested code snippets +- **Version information**: Specify applicable versions and platforms +- **Limitations**: Clearly state what the solution doesn't do + +### **Content Quality Standards** + +**Educational Value**: +- [ ] **Concept clarity**: Reader understands the fundamental idea +- [ ] **Context relevance**: Reader knows when to apply the knowledge +- [ ] **Practical application**: Reader can implement the solution +- [ ] **Problem prevention**: Reader avoids common mistakes +- [ ] **Next steps**: Reader knows where to continue learning + +**Technical Accuracy**: +- [ ] **Fact verification**: All technical details are correct +- [ ] **Code validation**: Examples compile and run correctly +- [ ] **Version compatibility**: Platform and version requirements clear +- [ ] **Security consideration**: Security implications addressed +- [ ] **Performance notes**: Performance characteristics documented + +## Document Types and Templates + +### **Technical Guides** + +**Focus**: Implementation and technical details +**Structure**: Problem → Solution → Implementation → Examples +**Education**: Explain the "why" behind technical choices + +### **Migration Documentation** + +**Focus**: Process and workflow guidance +**Structure**: Context → Preparation → Steps → Validation → Troubleshooting +**Education**: Help users understand migration benefits and risks + +### **Architecture Documentation** + +**Focus**: System design and decision rationale +**Structure**: Problem → Constraints → Alternatives → Decision → Implementation +**Education**: Explain design trade-offs and decision factors + +### **User Guides** + +**Focus**: Task completion and user empowerment +**Structure**: Goal → Prerequisites → Steps → Verification → Next Steps +**Education**: Help users understand the system's capabilities + +## Quality Assurance + +### **Review Checklist** + +**Educational Quality**: +- [ ] **Clear learning objective**: What will the reader learn? +- [ ] **Appropriate complexity**: Matches target audience knowledge +- [ ] **Progressive disclosure**: Information builds logically +- [ ] **Practical examples**: Real-world scenarios and use cases +- [ ] **Common questions**: Anticipates and answers reader questions + +**Technical Quality**: +- [ ] **Accuracy**: All technical details verified +- [ ] **Completeness**: Covers all necessary information +- [ ] **Consistency**: Terminology and formatting consistent +- [ ] **Currency**: Information is up-to-date +- [ ] **Accessibility**: Clear for target audience + +### **Validation Workflows** + +1. **Content Review**: Subject matter expert review +2. **Educational Review**: Learning effectiveness assessment +3. **Technical Review**: Accuracy and completeness validation +4. **User Testing**: Real user comprehension testing +5. **Continuous Improvement**: Regular updates based on feedback + +## Success Metrics + +### **Educational Effectiveness** + +- **Comprehension**: Users understand the concepts +- **Application**: Users can implement the solutions +- **Confidence**: Users feel capable and empowered +- **Efficiency**: Users complete tasks faster +- **Satisfaction**: Users find documentation helpful + +### **Technical Quality** + +- **Accuracy**: Zero technical errors +- **Completeness**: All necessary information included +- **Consistency**: Uniform style and format +- **Maintainability**: Easy to update and extend +- **Accessibility**: Clear for target audience + +## Common Pitfalls + +### **Educational Mistakes** + +- **Assumption overload**: Assuming too much prior knowledge +- **Information dump**: Overwhelming with details +- **Context missing**: Not explaining why something matters +- **Example poverty**: Insufficient practical examples +- **Feedback missing**: No way to verify understanding + +### **Technical Mistakes** + +- **Outdated information**: Not keeping content current +- **Incomplete coverage**: Missing important details +- **Inconsistent terminology**: Using different terms for same concepts +- **Poor examples**: Non-working or confusing code +- **Missing validation**: No way to verify correctness + +## Feedback and Improvement + +### **Continuous Learning** + +- **User feedback**: Collect and analyze user comments +- **Usage metrics**: Track document usage and effectiveness +- **Review cycles**: Regular content review and updates +- **Community input**: Engage users in documentation improvement +- **Best practices**: Stay current with documentation standards + +### **Quality Metrics** + +- **Readability scores**: Measure content clarity +- **User satisfaction**: Survey-based quality assessment +- **Task completion**: Success rate of documented procedures +- **Support reduction**: Decrease in help requests +- **Knowledge retention**: Long-term user understanding + +--- + +**See also**: + +- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards +- `.cursor/rules/docs/markdown_templates.mdc` for document templates +- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows +- `.cursor/rules/docs/meta_rule_usage_guide.md` for how to use meta-rules +- `.cursor/rules/core/base_context.mdc` for human competence principles + +**Status**: Active documentation meta-rule +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All bundled sub-rules +**Stakeholders**: Documentation team, Development team, Users 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/.gitignore b/.gitignore index 4202ef2a..bd97efcc 100644 --- a/.gitignore +++ b/.gitignore @@ -51,6 +51,9 @@ vendor/ # Build logs build_logs/ +# Guard feedback logs (for continuous improvement analysis) +.guard-feedback.log + # PWA icon files generated by capacitor-assets icons @@ -140,4 +143,5 @@ electron/out/ # Gradle cache files android/.gradle/file-system.probe android/.gradle/caches/ -coverage \ No newline at end of file +coverage +.husky-enabled \ No newline at end of file diff --git a/.husky/pre-commit b/.husky/pre-commit index 7d7b33e3..98b8a393 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,15 +1,33 @@ #!/usr/bin/env bash # # Husky Pre-commit Hook -# Runs Build Architecture Guard to check staged files +# Runs lint-fix and Build Architecture Guard on staged files # . "$(dirname -- "$0")/_/husky.sh" -echo "🔍 Running Build Architecture Guard (pre-commit)..." +echo "🔍 Running pre-commit hooks..." + +# Run lint-fix first +echo "📝 Running lint-fix..." +npm run lint-fix || { + echo + echo "❌ Linting failed. Please fix the issues and try again." + echo "💡 To bypass this check for emergency commits, use:" + echo " git commit --no-verify" + echo + exit 1 +} + +# Then run Build Architecture Guard +echo "🏗️ Running Build Architecture Guard..." bash ./scripts/build-arch-guard.sh --staged || { echo + echo "❌ Build Architecture Guard failed. Please fix the issues and try again." echo "💡 To bypass this check for emergency commits, use:" echo " git commit --no-verify" echo exit 1 } + +echo "✅ All pre-commit checks passed!" + 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/BUILDING.md b/BUILDING.md index 17c367d6..a1bb026e 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -78,6 +78,79 @@ npm run build:android:prod # Android production build npm run build:electron:prod # Electron production build ``` +### Build Architecture Guard + +The Build Architecture Guard protects your build system by enforcing documentation updates when build-critical files are modified. This ensures that all build changes are properly documented in `BUILDING.md`. + +#### How It Works + +- **Pre-commit Hook**: Automatically checks staged files before each commit +- **Protected Files**: Build scripts, config files, and platform-specific code +- **Documentation Requirement**: `BUILDING.md` must be updated alongside build changes +- **Automatic Enforcement**: Git hooks prevent commits without proper documentation +- **Feedback Collection**: Continuously improves through usage pattern analysis + +#### Protected File Patterns + +The guard monitors these sensitive paths: +- `vite.config.*` - Build configuration +- `scripts/**` - Build and utility scripts +- `electron/**` - Desktop application code +- `android/**` - Android platform code +- `ios/**` - iOS platform code +- `capacitor.config.ts` - Mobile configuration +- `capacitor-assets.config.json` - Android asset configuration +- `resources/**` - Source assets for Android resource generation +- `package.json` - Dependencies and scripts + +#### Enhanced Android Protection + +The guard now provides enhanced protection for Android build system changes: + +- **Asset Validation**: Protects `validate_android_assets()` function and resource paths +- **Resource Generation**: Monitors `capacitor-assets` integration and verification +- **API Routing**: Protects platform-specific IP handling (emulator vs physical device) +- **Build Modes**: Validates development/test/production mode handling +- **Resource Fallback**: Protects automatic regeneration of missing Android resources + +#### Using the Guard + +```bash +# Test the guard locally +./scripts/build-arch-guard.sh --staged + +# Analyze guard effectiveness (for maintainers) +./scripts/build-arch-guard.sh --feedback + +# Bypass for emergency commits (use sparingly) +git commit --no-verify + +# Setup the guard +npm run guard:setup +``` + +#### Troubleshooting + +If you encounter `mapfile: command not found` errors: +```bash +# Ensure script is executable +chmod +x scripts/build-arch-guard.sh + +# Test the script +./scripts/build-arch-guard.sh --help +``` + +#### Feedback and Continuous Improvement + +The guard system includes feedback mechanisms for continuous improvement: + +- **Automatic Logging**: All guard executions are logged for analysis +- **Pattern Analysis**: Identifies false positives/negatives and missing patterns +- **Maintainer Insights**: Use `--feedback` command to analyze guard effectiveness +- **Continuous Updates**: Guard rules and patterns are updated based on feedback + +**Note**: The guard is active and will block commits that modify build files without updating `BUILDING.md`. Recent enhancements provide better Android build system protection and feedback collection for continuous improvement. + ### Environment Configuration #### Quick Environment Setup @@ -116,6 +189,9 @@ npm run clean:android npm run build:ios # Regenerates iOS project npm run build:android # Regenerates Android project +# Fix Android asset issues +npm run assets:validate:android # Validates and regenerates missing Android assets + # Check environment npm run test:web # Verifies web setup ``` @@ -124,6 +200,7 @@ npm run test:web # Verifies web setup - **iOS**: Ensure Xcode and Command Line Tools are installed - **Android**: Ensure Android Studio and SDK are configured + - If you encounter "resource drawable/splash not found" errors, run `npm run assets:validate:android` - **Electron**: Ensure platform-specific build tools are installed ### Next Steps @@ -267,17 +344,10 @@ current version to test DB migrations. [online](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/releases) or `git tag 1.0.2 && git push origin 1.0.2`. -- For test, build the app (because test server is not yet set up to build): +- For test, build the app: ```bash -TIME_SAFARI_APP_TITLE="TimeSafari_Test" \ -VITE_APP_SERVER=https://test.timesafari.app \ -VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F \ -VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch \ -VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app \ -VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch \ -VITE_DEFAULT_PUSH_SERVER=https://test.timesafari.app \ -VITE_PASSKEYS_ENABLED=true npm run build:web +npm run build:web:test ``` ... and transfer to the test server: @@ -1136,6 +1206,69 @@ npm run build:android:assets # Generate assets only npm run build:android:deploy # Build and deploy to connected device ``` +#### Android Asset Validation + +The Android build system now includes automatic asset validation to prevent build failures caused by missing resources. This system: + +- **Validates Source Assets**: Checks that required source files exist in `resources/` +- **Checks Android Resources**: Verifies that generated Android resources are present +- **Auto-Regenerates**: Automatically regenerates missing resources when detected +- **Provides Clear Errors**: Gives helpful guidance when issues occur + +##### Asset Validation Commands + +```bash +# Validate and regenerate Android assets if needed +npm run assets:validate:android + +# Alternative command for asset validation +./scripts/build-android.sh --assets-only + +# Check asset configuration only (no regeneration) +npm run assets:validate +``` + +##### What Gets Validated + +**Source Assets (Required):** +- `resources/icon.png` - App icon source +- `resources/splash.png` - Splash screen source +- `resources/splash_dark.png` - Dark mode splash source + +**Android Resources (Generated):** +- `android/app/src/main/res/drawable/splash.png` - Splash screen drawable +- `android/app/src/main/res/mipmap-*/ic_launcher.png` - App icons for all densities +- `android/app/src/main/res/mipmap-*/ic_launcher_round.png` - Round app icons for all densities + +##### Automatic Validation + +Asset validation runs automatically during all Android builds: + +```bash +# All these commands now include asset validation +npm run build:android:studio +npm run build:android:prod +npm run build:android:debug +``` + +If validation fails, the build stops with clear error messages and guidance on how to fix the issues. + +##### Troubleshooting Asset Issues + +If you encounter asset-related build failures: + +```bash +# Check what's missing +npm run assets:validate:android + +# Clean and regenerate everything +npm run clean:android +npm run assets:validate:android +npm run build:android:studio +``` + +For more detailed information, see [Android Asset Validation Documentation](doc/android-asset-validation.md). + #### Android Automated Build Script The recommended way to build for Android is using the automated build script: @@ -2539,3 +2672,50 @@ All scripts use consistent error handling: **Note**: This documentation is maintained alongside the build system. For the most up-to-date information, refer to the actual script files and Vite configuration files in the repository. + +--- + +## Build Changes Changelog + +### 2025-08-21 - Cursor Rules Refactoring and Build System Updates + +#### Package Dependencies Updated +- **Added**: `markdownlint-cli2` v0.18.1 - Modern markdown linting with improved performance +- **Added**: `@commitlint/cli` v18.6.1 - Conventional commit message validation +- **Added**: `@commitlint/config-conventional` v18.6.2 - Conventional commit standards +- **Updated**: `husky` v9.0.11 - Git hooks management +- **Updated**: `lint-staged` v15.2.2 - Pre-commit linting automation + +#### Build Script Improvements +- **Markdown Linting**: Replaced custom markdown scripts with `markdownlint-cli2` + - **Before**: `./scripts/fix-markdown.sh` and `./scripts/validate-markdown.sh` + - **After**: `markdownlint-cli2 --fix` and `markdownlint-cli2` + - **Benefits**: Faster execution, better error reporting, modern markdown standards + +#### Lint-Staged Configuration Enhanced +- **Added**: Markdown file linting to pre-commit hooks + - **Pattern**: `*.{md,markdown,mdc}` files now automatically formatted + - **Command**: `markdownlint-cli2 --fix` runs before each commit + - **Coverage**: All markdown files including `.mdc` cursor rules + +#### Commit Message Standards +- **Added**: Conventional commit validation via commitlint +- **Configuration**: Extends `@commitlint/config-conventional` +- **Enforcement**: Ensures consistent commit message format across the project + +#### Node.js Version Requirements +- **Updated**: Minimum Node.js version requirements for new dependencies +- **markdownlint-cli2**: Requires Node.js >=20 +- **Various utilities**: Require Node.js >=18 for modern ES features + +#### Build Process Impact +- **No Breaking Changes**: All existing build commands continue to work +- **Improved Quality**: Better markdown formatting and commit message standards +- **Enhanced Automation**: More comprehensive pre-commit validation +- **Performance**: Faster markdown linting with modern tooling + +--- + +**Note**: This documentation is maintained alongside the build system. For the +most up-to-date information, refer to the actual script files and Vite +configuration files in the repository. diff --git a/README.md b/README.md index c39fbde9..f11263dd 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,26 @@ -# Time Safari Application +# TimeSafari.app - Crowd-Funder for Time - PWA -**Author**: Matthew Raymer -**Version**: 1.0.8-beta -**Description**: Time Safari Application +[Time Safari](https://timesafari.org/) allows people to ease into collaboration: start with expressions of gratitude +and expand to crowd-fund with time & money, then record and see the impact of contributions. + +## Roadmap + +See [ClickUp](https://sharing.clickup.com/9014278710/l/h/8cmnyhp-174/10573fec74e2ba0) for current priorities. + +## Setup & Building + +Quick start: + +* For setup, we recommend [pkgx](https://pkgx.dev), which installs what you need (either automatically or with the `dev` command). Core dependencies are typescript & npm; when building for other platforms, you'll need other things such as those in the pkgx.yaml & BUILDING.md files. + +```bash +npm install +npm run build:web:serve -- --test +``` + +To be able to make submissions: go to "profile" (bottom left), go to the bottom and expand "Show Advanced Settings", go to the bottom and to the "Test Page", and finally "Become User 0" to see all the functionality. + +See [BUILDING.md](BUILDING.md) for comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker). ## 🛡️ Build Architecture Guard @@ -36,40 +54,242 @@ git commit --no-verify git push --no-verify ``` -**📚 Full documentation**: See `README-BUILD-GUARD.md` +**📚 Full documentation**: See `doc/README-BUILD-GUARD.md` -## 🚀 Quick Start +## Development Database Clearing -### Prerequisites +TimeSafari provides a simple script-based approach to clear the local database (not the claim server) for development purposes. -- Node.js 18+ -- npm, yarn, or pnpm -- Git +## Logging Configuration -### Installation +TimeSafari supports configurable logging levels via the `VITE_LOG_LEVEL` environment variable. This allows developers to control console output verbosity without modifying code. + +### Quick Usage ```bash -npm install -npm run guard:setup # Sets up Build Architecture Guard +# Show only errors +VITE_LOG_LEVEL=error npm run dev + +# Show warnings and errors +VITE_LOG_LEVEL=warn npm run dev + +# Show info, warnings, and errors (default) +VITE_LOG_LEVEL=info npm run dev + +# Show all log levels including debug +VITE_LOG_LEVEL=debug npm run dev +``` + +### Available Levels + +- **`error`**: Critical errors only +- **`warn`**: Warnings and errors (default for production web) +- **`info`**: Info, warnings, and errors (default for development/capacitor) +- **`debug`**: All log levels including verbose debugging + +See [Logging Configuration Guide](doc/logging-configuration.md) for complete details. + +### Quick Usage +```bash +# Run the database clearing script +./scripts/clear-database.sh + +# Then restart your development server +npm run build:electron:dev # For Electron +npm run build:web:dev # For Web +``` + +### What It Does + +#### **Electron (Desktop App)** +- Automatically finds and clears the SQLite database files +- Works on Linux, macOS, and Windows +- Clears all data and forces fresh migrations on next startup + +#### **Web Browser** +- Provides instructions for using custom browser data directories +- Shows manual clearing via browser DevTools +- Ensures reliable database clearing without browser complications + +### Safety Features +- ✅ **Interactive Script**: Guides you through the process +- ✅ **Platform Detection**: Automatically detects your OS +- ✅ **Clear Instructions**: Step-by-step guidance for each platform +- ✅ **Safe Paths**: Only clears TimeSafari-specific data + +### Manual Commands (if needed) + +#### **Electron Database Location** +```bash +# Linux +rm -rf ~/.config/TimeSafari/* + +# macOS +rm -rf ~/Library/Application\ Support/TimeSafari/* + +# Windows +rmdir /s /q %APPDATA%\TimeSafari ``` -### Development +#### **Web Browser (Custom Data Directory)** +```bash +# Create isolated browser profile +mkdir ~/timesafari-dev-data +``` + +## Domain Configuration + +TimeSafari uses a centralized domain configuration system to ensure consistent +URL generation across all environments. This prevents localhost URLs from +appearing in shared links during development. + +### Key Features +- ✅ **Production URLs for Sharing**: All copy link buttons use production domain +- ✅ **Environment-Specific Internal URLs**: Internal operations use appropriate + environment URLs +- ✅ **Single Point of Control**: Change domain in one place for entire app +- ✅ **Type-Safe Configuration**: Full TypeScript support + +### Quick Reference + +```typescript +// For sharing functionality (environment-specific) +import { APP_SERVER } from "@/constants/app"; +const shareLink = `${APP_SERVER}/deep-link/claim/123`; + +// For internal operations (environment-specific) +import { APP_SERVER } from "@/constants/app"; +const apiUrl = `${APP_SERVER}/api/claim/123`; +``` + +### Documentation + +- [Constants and Configuration](src/constants/app.ts) - Core constants + +## Tests + +See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions. + +## Asset Management + +TimeSafari uses a standardized asset configuration system for consistent +icon and splash screen generation across all platforms. + +### Asset Sources + +- **Single source of truth**: `resources/` directory (Capacitor default) +- **Source files**: `icon.png`, `splash.png`, `splash_dark.png` +- **Format**: PNG or SVG files for optimal quality + +### Asset Generation + +- **Configuration**: `config/assets/capacitor-assets.config.json` +- **Schema validation**: `config/assets/schema.json` +- **Build-time generation**: Platform assets generated via `capacitor-assets` +- **No VCS commits**: Generated assets are never committed to version control + +### Development Commands ```bash -npm run build:web:dev # Build web version -npm run build:ios:test # Build iOS test version -npm run build:android:test # Build Android test version -npm run build:electron:dev # Build Electron dev version +# Generate/update asset configurations +npm run assets:config + +# Validate asset configurations +npm run assets:validate + +# Clean generated platform assets (local dev only) +npm run assets:clean + +# Build with asset generation +npm run build:native ``` -### Testing +### Environment Setup & Dependencies + +Before building the application, ensure your development environment is properly +configured: ```bash -npm run test:web # Run web tests -npm run test:mobile # Run mobile tests -npm run test:all # Run all tests +# Install all dependencies (required first time and after updates) +npm install + +# Validate your development environment +npm run check:dependencies + +# Check prerequisites for testing +npm run test:prerequisites ``` +**Common Issues & Solutions**: + +- **"tsx: command not found"**: Run `npm install` to install devDependencies +- **"capacitor-assets: command not found"**: Ensure `@capacitor/assets` is installed +- **Build failures**: Run `npm run check:dependencies` to diagnose environment issues + +**Required Versions**: +- Node.js: 18+ (LTS recommended) +- npm: 8+ (comes with Node.js) +- Platform-specific tools: Android Studio, Xcode (for mobile builds) + +### Platform Support + +- **Android**: Adaptive icons with foreground/background, monochrome support +- **iOS**: LaunchScreen storyboard preferred, splash assets when needed +- **Web**: PWA icons generated during build to `dist/` (not committed) + +### Font Awesome Icons + +To add a Font Awesome icon, add to `fontawesome.ts` and reference with +`font-awesome` element and `icon` attribute with the hyphenated name. + +## Other + +### Reference Material + +* Notifications can be type of `toast` (self-dismiss), `info`, `success`, `warning`, and `danger`. + They are done via [notiwind](https://www.npmjs.com/package/notiwind) and set up in App.vue. + +* [Customize Vue configuration](https://cli.vuejs.org/config/). + +* If you are deploying in a subdirectory, add it to `publicPath` in vue.config.js, eg: `publicPath: "/app/time-tracker/",` + +### Code Organization + +The project uses a centralized approach to type definitions and interfaces: + +* `src/interfaces/` - Contains all TypeScript interfaces and type definitions + * `deepLinks.ts` - Deep linking type system and Zod validation schemas + * `give.ts` - Give-related interfaces and type definitions + * `claims.ts` - Claim-related interfaces and verifiable credentials + * `common.ts` - Shared interfaces and utility types + * Other domain-specific interface files + +Key principles: +- All interfaces and types are defined in the interfaces folder +- Zod schemas are used for runtime validation and type generation +- Domain-specific interfaces are separated into their own files +- Common interfaces are shared through `common.ts` +- Type definitions are generated from Zod schemas where possible + +### Database Architecture + +The application uses a platform-agnostic database layer with Vue mixins for service access: + +* `src/services/PlatformService.ts` - Database interface definition +* `src/services/PlatformServiceFactory.ts` - Platform-specific service factory +* `src/services/AbsurdSqlDatabaseService.ts` - SQLite implementation +* `src/utils/PlatformServiceMixin.ts` - Vue mixin for database access with caching +* `src/db/` - Legacy Dexie database (migration in progress) + +**Development Guidelines**: + +- Always use `PlatformServiceMixin` for database operations in components +- Test with PlatformServiceMixin for new features +- Use migration tools for data transfer between systems +- Leverage mixin's ultra-concise methods: `$db()`, `$exec()`, `$one()`, `$contacts()`, `$settings()` + +**Architecture Decision**: The project uses Vue mixins over Composition API composables for platform service access. See [Architecture Decisions](doc/architecture-decisions.md) for detailed rationale. + ## 📁 Project Structure ```text @@ -82,24 +302,9 @@ timesafari/ ├── 📁 .husky/ # Git hooks (Build Architecture Guard) ├── 📄 BUILDING.md # Build system documentation ├── 📄 pull_request_template.md # PR template -└── 📄 README-BUILD-GUARD.md # Guard system documentation +└── 📄 doc/README-BUILD-GUARD.md # Guard system documentation ``` -## 🔧 Build System - -This project supports multiple platforms: - -- **Web**: Vite-based build with service worker support -- **Mobile**: Capacitor-based iOS and Android builds -- **Desktop**: Electron-based cross-platform desktop app -- **Docker**: Containerized deployment options - -## 📚 Documentation - -- **`BUILDING.md`** - Complete build system guide -- **`README-BUILD-GUARD.md`** - Build Architecture Guard documentation -- **`pull_request_template.md`** - PR template for build changes - ## 🤝 Contributing 1. **Follow the Build Architecture Guard** - Update BUILDING.md when modifying build files @@ -107,12 +312,15 @@ This project supports multiple platforms: 3. **Test your changes** - Ensure builds work on affected platforms 4. **Document updates** - Keep BUILDING.md current and accurate -## 📄 License - -[Add your license information here] +## Kudos ---- +Gifts make the world go 'round! -**Note**: The Build Architecture Guard is active and will block -commits/pushes that modify build files without proper documentation -updates. See `README-BUILD-GUARD.md` for complete details. +* [WebStorm by JetBrains](https://www.jetbrains.com/webstorm/) for the free open-source license +* [Máximo Fernández](https://medium.com/@maxfarenas) for the 3D [code](https://github.com/maxfer03/vue-three-ns) and [explanatory post](https://medium.com/nicasource/building-an-interactive-web-portfolio-with-vue-three-js-part-three-implementing-three-js-452cb375ef80) +* [Many tools & libraries](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/src/branch/master/package.json#L10) such as Nodejs.org, IntelliJ Idea, Veramo.io, Vuejs.org, threejs.org +* [Bush 3D model](https://sketchfab.com/3d-models/lupine-plant-bf30f1110c174d4baedda0ed63778439) +* [Forest floor image](https://www.goodfreephotos.com/albums/textures/leafy-autumn-forest-floor.jpg) +* Time Safari logo assisted by [DALL-E in ChatGPT](https://chat.openai.com/g/g-2fkFE8rbu-dall-e) +* [DiceBear](https://www.dicebear.com/licenses/) and [Avataaars](https://www.dicebear.com/styles/avataaars/#details) for human-looking identicons +* Some gratitude prompts thanks to [Develop Good Habits](https://www.developgoodhabits.com/gratitude-journal-prompts/) diff --git a/README-BUILD-GUARD.md b/doc/README-BUILD-GUARD.md similarity index 86% rename from README-BUILD-GUARD.md rename to doc/README-BUILD-GUARD.md index 9b617edb..36f4c21a 100644 --- a/README-BUILD-GUARD.md +++ b/doc/README-BUILD-GUARD.md @@ -230,6 +230,44 @@ git diff --name-only --cached 3. **Team training** - Help developers understand the system 4. **Continuous improvement** - Refine patterns and error messages +## 🚨 **Troubleshooting** + +### Common Issues + +#### mapfile Command Not Found + +**Problem**: Pre-commit hook fails with `mapfile: command not found` + +**Cause**: The `mapfile` command is bash-specific and not available in all shell environments + +**Solution**: The script has been updated to use portable alternatives. If you encounter this issue: + +```bash +# Verify the script is executable +chmod +x scripts/build-arch-guard.sh + +# Test the script directly +./scripts/build-arch-guard.sh --help + +# Check your shell environment +echo $SHELL +bash --version +``` + +**Prevention**: Ensure your development environment uses bash and the script has proper permissions + +### False Positives + +```bash +# If guard blocks legitimate changes, check: +# 1. Are you modifying a protected file pattern? +# 2. Did you update BUILDING.md? +# 3. Is BUILDING.md staged for commit? + +# View what the guard sees +git diff --name-only --cached +``` + ## 🔄 **Customization** ### Adding New Protected Paths @@ -288,3 +326,11 @@ Track the effectiveness of your Build Architecture Guard: **Dependencies**: Husky, Git, Bash **Maintainer**: Development team **Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh` + +## 📝 **Changelog** + +### 2025-08-22 - Shell Compatibility Fix +- **Fixed**: Replaced `mapfile` command with portable alternative for cross-shell compatibility +- **Impact**: Resolves "mapfile: command not found" errors in pre-commit hooks +- **Files**: `scripts/build-arch-guard.sh` +- **Testing**: Script now works across different shell environments diff --git a/doc/android-asset-validation.md b/doc/android-asset-validation.md new file mode 100644 index 00000000..db77aeb8 --- /dev/null +++ b/doc/android-asset-validation.md @@ -0,0 +1,238 @@ +# Android Asset Validation System + +**Author**: Matthew Raymer +**Date**: 2025-08-22 +**Status**: 🎯 **ACTIVE** - Production Ready + +## Overview + +The Android Asset Validation System automatically detects and fixes missing Android resources before building, preventing common build failures related to missing splash screens and app icons. + +## Problem Solved + +Previously, Android builds would fail with errors like: +``` +error: resource drawable/splash (aka app.timesafari.app:drawable/splash) not found. +error: resource mipmap/ic_launcher (aka app.timesafari.app:mipmap/ic_launcher) not found. +``` + +This happened when: +- Source assets existed but weren't generated into Android resources +- Android resource directories were missing +- Asset generation tools weren't run before building + +## Solution + +### Enhanced Build Script Validation + +The `scripts/build-android.sh` script now includes comprehensive asset validation that: + +1. **Checks Source Assets**: Validates that required source files exist in `resources/` +2. **Checks Android Resources**: Verifies that generated Android resources exist +3. **Auto-Regenerates**: Automatically regenerates missing resources when detected +4. **Verifies Results**: Confirms that regeneration was successful + +### Validation Process + +```bash +# Validates and regenerates if needed +npm run assets:validate:android + +# Full build with validation +npm run build:android:studio +``` + +### What Gets Validated + +#### Source Assets (Required) +- `resources/icon.png` - App icon source +- `resources/splash.png` - Splash screen source +- `resources/splash_dark.png` - Dark mode splash source + +#### Android Resources (Generated) +- `android/app/src/main/res/drawable/splash.png` - Splash screen drawable +- `android/app/src/main/res/mipmap-*/ic_launcher.png` - App icons for all densities +- `android/app/src/main/res/mipmap-*/ic_launcher_round.png` - Round app icons for all densities + +### Density Levels Checked +- `mipmap-mdpi` (1x) +- `mipmap-hdpi` (1.5x) +- `mipmap-xhdpi` (2x) +- `mipmap-xxhdpi` (3x) +- `mipmap-xxxhdpi` (4x) + +## Usage + +### Automatic Validation (Recommended) +The validation runs automatically during all Android builds: + +```bash +# Development build with validation +npm run build:android:studio + +# Production build with validation +npm run build:android:prod + +# Debug build with validation +npm run build:android:debug +``` + +### Manual Validation +Run validation only to check/fix assets: + +```bash +# Validate and regenerate if needed +npm run assets:validate:android + +# Alternative command +./scripts/build-android.sh --assets-only +``` + +### Validation Only (No Regeneration) +Check configuration without fixing: + +```bash +npm run assets:validate +``` + +## Error Handling + +### Missing Source Assets +If source assets are missing, the build fails with clear error messages: + +``` +[ERROR] Missing source assets: +[ERROR] - resources/icon.png +[ERROR] - resources/splash.png +[ERROR] Please ensure all required assets are present in the resources/ directory. +``` + +### Missing Generated Resources +If generated resources are missing, they're automatically regenerated: + +``` +[WARN] Missing Android resources detected: +[WARN] - drawable/splash.png +[WARN] - mipmap-mdpi/ic_launcher.png +[INFO] Regenerating Android assets... +[SUCCESS] Android assets regenerated successfully +``` + +### Generation Failure +If regeneration fails, helpful guidance is provided: + +``` +[ERROR] Failed to generate Android assets +[INFO] You may need to manually create the missing resources: +[INFO] - android/app/src/main/res/drawable/splash.png +[INFO] - android/app/src/main/res/mipmap-mdpi/ic_launcher.png +``` + +## Integration Points + +### Build Script Integration +The validation is integrated into the main build process: + +```bash +# In scripts/build-android.sh +validate_dependencies +validate_android_assets || { + log_error "Android asset validation failed. Please fix the issues above and try again." + exit 9 +} +``` + +### NPM Scripts +New npm scripts for asset management: + +```json +{ + "assets:validate": "npx tsx scripts/assets-validator.ts", + "assets:validate:android": "./scripts/build-android.sh --assets-only", + "assets:clean": "rimraf android/app/src/main/res/mipmap-* ios/App/App/Assets.xcassets/**/AppIcon*.png ios/App/App/Assets.xcassets/**/Splash*.png || true" +} +``` + +## Benefits + +### For Developers +- **No More Build Failures**: Automatic detection and fixing of missing resources +- **Faster Development**: No need to manually run asset generation tools +- **Clear Error Messages**: Helpful guidance when issues occur +- **Consistent Results**: Same validation on all development machines + +### For CI/CD +- **Reliable Builds**: Consistent asset validation across environments +- **Early Detection**: Catches issues before they reach production +- **Automated Fixes**: Self-healing builds when possible + +### For Project Maintenance +- **Reduced Support**: Fewer "build doesn't work" issues +- **Documentation**: Clear requirements for required assets +- **Standardization**: Consistent asset structure across the project + +## Troubleshooting + +### Common Issues + +#### "No assets found in the asset path" +This occurs when the `assets/` directory is empty. The validation system automatically copies source assets and regenerates them. + +#### "Failed to generate Android assets" +Check that: +- Source assets exist in `resources/` +- `@capacitor/assets` is installed +- You have write permissions to the Android directories + +#### "Asset generation completed but some resources are still missing" +This indicates a problem with the asset generation tool. Try: +1. Running `npm install` to ensure dependencies are up to date +2. Manually running `npx @capacitor/assets generate` +3. Checking the asset generation logs for specific errors + +### Manual Recovery +If automatic regeneration fails, you can manually create the missing resources: + +```bash +# Create missing directories +mkdir -p android/app/src/main/res/drawable +mkdir -p android/app/src/main/res/mipmap-{mdpi,hdpi,xhdpi,xxhdpi,xxxhdpi} + +# Copy source assets to assets directory +cp resources/icon.png assets/ +cp resources/splash.png assets/ +cp resources/splash_dark.png assets/ + +# Generate assets manually +npx @capacitor/assets generate + +# Clean up +rm assets/icon.png assets/splash.png assets/splash_dark.png +``` + +## Future Enhancements + +### Planned Improvements +- **iOS Asset Validation**: Extend validation to iOS assets +- **Asset Quality Checks**: Validate image dimensions and formats +- **Performance Optimization**: Cache validation results +- **CI/CD Integration**: Add validation to GitHub Actions + +### Configuration Options +- **Custom Asset Paths**: Support for different asset directory structures +- **Validation Rules**: Configurable validation requirements +- **Skip Options**: Ability to skip validation for specific scenarios + +## References + +- [Capacitor Assets Documentation](https://github.com/ionic-team/capacitor-assets) +- [Android Resource System](https://developer.android.com/guide/topics/resources/providing-resources) +- [Build Script Documentation](./build-android.sh) +- [Asset Configuration](./capacitor-assets.config.json) + +--- + +**Status**: Active validation system +**Priority**: High +**Maintainer**: Development team +**Next Review**: 2025-09-22 diff --git a/doc/meta_rule_usage_guide.md b/doc/meta_rule_usage_guide.md new file mode 100644 index 00000000..85d2b25b --- /dev/null +++ b/doc/meta_rule_usage_guide.md @@ -0,0 +1,272 @@ +# Meta-Rule Usage Guide: How to Use Meta-Rules in Practice + +**Author**: Matthew Raymer +**Date**: 2025-08-21 +**Status**: 🎯 **ACTIVE** - Comprehensive meta-rule usage guide + +## Overview + +This guide explains how to use the TimeSafari meta-rule system in practice. +Meta-rules are high-level rule bundles that provide workflow-specific guidance +for different types of tasks. + +**Educational Goal**: Help developers understand when and how to apply +meta-rules to maximize their effectiveness and avoid common mistakes. + +## Why Meta-Rules Matter + +**Meta-rules solve the problem of rule overload** by bundling related rules +into logical workflows. Instead of manually selecting 10+ individual rules, +you apply 1-3 meta-rules that automatically include everything you need. + +### **Benefits of Using Meta-Rules** + +- **Faster Setup**: No need to manually select individual rules +- **Better Coverage**: Ensures you don't miss important rules +- **Workflow Consistency**: Standardized approaches across the team +- **Learning Efficiency**: Learn workflows, not individual rules +- **Quality Assurance**: Built-in validation and feedback mechanisms + +## Meta-Rule Selection Strategy + +### **Step 1: Always Start with Core Always-On** + +**Every single interaction** starts with: +``` +meta_core_always_on.mdc +``` + +This provides the foundation: human competence principles, time standards, +version control, and application context. + +### **Step 2: Identify Your Primary Task Type** + +Choose the meta-rule that matches your main objective: + +| **Task Type** | **Primary Meta-Rule** | **When to Use** | +|---------------|------------------------|------------------| +| **Research/Investigation** | `meta_research.mdc` | Bug diagnosis, feasibility research, code analysis | +| **Feature Planning** | `meta_feature_planning.mdc` | New feature design, requirements analysis | +| **Feature Implementation** | `meta_feature_implementation.mdc` | Building features, coding, testing | +| **Bug Diagnosis** | `meta_bug_diagnosis.mdc` | Investigating issues, root cause analysis | +| **Bug Fixing** | `meta_bug_fixing.mdc` | Implementing fixes, validation | +| **Documentation** | `meta_documentation.mdc` | Writing docs, creating guides, tutorials | + +### **Step 3: Add Context-Specific Meta-Rules (Optional)** + +For complex tasks, you might combine multiple meta-rules: + +``` +meta_core_always_on + meta_research + meta_bug_diagnosis +``` + +## Practical Usage Examples + +### **Example 1: Bug Investigation** + +**Scenario**: User reports that the contact list isn't loading properly + +**Meta-Rule Selection**: +``` +meta_core_always_on + meta_research + meta_bug_diagnosis +``` + +**What This Gives You**: +- **Core Always-On**: Human competence focus, time standards, context +- **Research**: Systematic investigation methodology, evidence collection +- **Bug Diagnosis**: Defect analysis framework, root cause identification + +**Workflow**: +1. Apply core always-on for foundation +2. Use research meta-rule for systematic investigation +3. Apply bug diagnosis for defect analysis +4. Follow the bundled workflow automatically + +### **Example 2: Feature Development** + +**Scenario**: Building a new contact search feature + +**Meta-Rule Selection**: +``` +meta_core_always_on + meta_feature_planning + meta_feature_implementation +``` + +**What This Gives You**: +- **Core Always-On**: Foundation principles and context +- **Feature Planning**: Requirements analysis, architecture planning +- **Feature Implementation**: Development workflow, testing strategy + +**Workflow**: +1. Start with core always-on +2. Use feature planning for design and requirements +3. Switch to feature implementation for coding and testing + +### **Example 3: Documentation Creation** + +**Scenario**: Writing a migration guide for the new database system + +**Meta-Rule Selection**: +``` +meta_core_always_on + meta_documentation +``` + +**What This Gives You**: +- **Core Always-On**: Foundation and context +- **Documentation**: Educational focus, templates, quality standards + +**Workflow**: +1. Apply core always-on for foundation +2. Use documentation meta-rule for educational content creation +3. Follow educational templates and quality standards + +## Meta-Rule Application Process + +### **1. Load the Meta-Rule** + +When you start a task, explicitly state which meta-rules you're applying: + +``` +"I'm applying meta_core_always_on + meta_research for this bug investigation." +``` + +### **2. Follow the Bundled Workflow** + +Each meta-rule provides a complete workflow. Follow it step-by-step: + +- **Research Meta-Rule**: Investigation → Evidence → Analysis → Conclusion +- **Feature Planning**: Requirements → Architecture → Strategy → Validation +- **Bug Diagnosis**: Problem → Evidence → Root Cause → Solution + +### **3. Use the Bundled Rules** + +Meta-rules automatically include all necessary sub-rules. You don't need to +manually select individual rules - they're already bundled. + +### **4. Validate Against Success Criteria** + +Each meta-rule includes success criteria. Use these to validate your work: + +- [ ] **Educational Quality**: Content increases human competence +- [ ] **Technical Quality**: All technical details are accurate +- [ ] **Workflow Completion**: All required steps completed +- [ ] **Quality Standards**: Meets defined quality criteria + +## Common Meta-Rule Combinations + +### **Research + Diagnosis** +``` +meta_core_always_on + meta_research + meta_bug_diagnosis +``` +**Use for**: Complex bug investigations requiring systematic analysis + +### **Planning + Implementation** +``` +meta_core_always_on + meta_feature_planning + meta_feature_implementation +``` +**Use for**: End-to-end feature development from concept to deployment + +### **Research + Planning** +``` +meta_core_always_on + meta_research + meta_feature_planning +``` +**Use for**: Feasibility research and solution design + +### **Documentation + Context** +``` +meta_core_always_on + meta_documentation + [context-specific] +``` +**Use for**: Creating comprehensive, educational documentation + +## Best Practices + +### **✅ Do These Things** + +- **Always start with core always-on** - it's the foundation +- **Choose the primary meta-rule** that matches your main task +- **Follow the bundled workflow** step-by-step +- **Use success criteria** to validate your work +- **Collect feedback** on meta-rule effectiveness + +### **❌ Avoid These Mistakes** + +- **Don't skip core always-on** - you'll lose the foundation +- **Don't apply too many meta-rules** - stick to 2-3 maximum +- **Don't ignore the bundled workflow** - follow it systematically +- **Don't forget validation** - use the success criteria +- **Don't skip feedback collection** - it improves the system + +## Troubleshooting Common Issues + +### **Problem**: Meta-rules seem to conflict + +**Solution**: Meta-rules are designed to work together. If you see conflicts, +you're probably applying too many. Stick to 2-3 meta-rules maximum. + +### **Problem**: I don't know which meta-rule to use + +**Solution**: Start with your primary task type. If you're investigating a bug, +use research + bug diagnosis. If you're building a feature, use feature +planning + implementation. + +### **Problem**: The meta-rule workflow seems too complex + +**Solution**: Meta-rules bundle complexity into manageable workflows. Follow +the steps one at a time. The complexity is already organized for you. + +### **Problem**: I'm not seeing the expected behavior + +**Solution**: Ensure you're following the meta-rule workflow step-by-step. +Meta-rules provide guidance, but you still need to execute the workflow. + +## Feedback and Improvement + +### **Rate Your Experience** + +After using a meta-rule, provide feedback: + +- **Effectiveness**: How well did the meta-rule work? (1-5 scale) +- **Time Saved**: How much time did it save you? +- **Quality Improvement**: Did it improve your work quality? +- **Recommendation**: Would you recommend it to others? + +### **Continuous Improvement** + +Meta-rules evolve based on feedback: + +- **Usage patterns** - How teams use the rules +- **Effectiveness ratings** - What works and what doesn't +- **Integration feedback** - How well rules work together +- **Quality metrics** - Impact on work quality + +## Quick Reference + +### **Meta-Rule Selection Matrix** + +| **Task** | **Primary** | **Secondary** | **Tertiary** | +|----------|-------------|---------------|---------------| +| **Bug Investigation** | `meta_research` | `meta_bug_diagnosis` | - | +| **Feature Development** | `meta_feature_planning` | `meta_feature_implementation` | - | +| **Documentation** | `meta_documentation` | - | - | +| **Complex Research** | `meta_research` | `meta_bug_diagnosis` | `meta_feature_planning` | + +### **Always Remember** + +1. **Start with core always-on** - foundation for everything +2. **Choose your primary meta-rule** - matches your main task +3. **Follow the bundled workflow** - step-by-step execution +4. **Validate against success criteria** - ensure quality +5. **Provide feedback** - help improve the system + +--- + +**See also**: + +- `.cursor/rules/meta_rule_architecture.md` for meta-rule structure overview +- `.cursor/rules/meta_core_always_on.mdc` for foundation rules +- `.cursor/rules/README.md` for complete rule organization + +**Status**: Active usage guide +**Priority**: High +**Estimated Effort**: Ongoing reference +**Dependencies**: All meta-rules +**Stakeholders**: Development team, Documentation team diff --git a/package-lock.json b/package-lock.json index 4806f89f..fea161a9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "timesafari", - "version": "1.0.8-beta", + "version": "1.1.0-beta", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "timesafari", - "version": "1.0.8-beta", + "version": "1.1.0-beta", "dependencies": { "@capacitor-community/electron": "^5.0.1", "@capacitor-community/sqlite": "6.0.2", @@ -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 77a4ac92..78226938 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "timesafari", - "version": "1.0.8-beta", + "version": "1.1.0-beta", "description": "Time Safari Application", "author": { "name": "Time Safari Team" @@ -31,6 +31,7 @@ "build:native": "vite build && npx cap sync && npx capacitor-assets generate", "assets:config": "npx tsx scripts/assets-config.ts", "assets:validate": "npx tsx scripts/assets-validator.ts", + "assets:validate:android": "./scripts/build-android.sh --assets-only", "assets:clean": "rimraf android/app/src/main/res/mipmap-* ios/App/App/Assets.xcassets/**/AppIcon*.png ios/App/App/Assets.xcassets/**/Splash*.png || true", "build:ios": "./scripts/build-ios.sh", "build:ios:dev": "./scripts/build-ios.sh --dev", @@ -98,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", @@ -132,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", @@ -226,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", @@ -253,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", diff --git a/scripts/build-android.sh b/scripts/build-android.sh index c795a4b0..f57f70c7 100755 --- a/scripts/build-android.sh +++ b/scripts/build-android.sh @@ -41,7 +41,7 @@ # 6 - Capacitor sync failed # 7 - Asset generation failed # 8 - Android Studio launch failed -# 9 - Resource check failed +# 9 - Android asset validation failed # Exit on any error set -e @@ -74,6 +74,117 @@ validate_dependencies() { log_success "All critical dependencies validated successfully" } +# Function to validate Android assets and resources +validate_android_assets() { + log_info "Validating Android assets and resources..." + + # Check if source assets exist + local missing_assets=() + + if [ ! -f "resources/icon.png" ]; then + missing_assets+=("resources/icon.png") + fi + + if [ ! -f "resources/splash.png" ]; then + missing_assets+=("resources/splash.png") + fi + + if [ ! -f "resources/splash_dark.png" ]; then + missing_assets+=("resources/splash_dark.png") + fi + + if [ ${#missing_assets[@]} -gt 0 ]; then + log_error "Missing source assets:" + for asset in "${missing_assets[@]}"; do + log_error " - $asset" + done + log_error "Please ensure all required assets are present in the resources/ directory." + return 1 + fi + + # Check if Android drawable resources exist + local missing_drawables=() + + if [ ! -f "android/app/src/main/res/drawable/splash.png" ]; then + missing_drawables+=("drawable/splash.png") + fi + + # Check if mipmap resources exist + local missing_mipmaps=() + local mipmap_dirs=("mipmap-mdpi" "mipmap-hdpi" "mipmap-xhdpi" "mipmap-xxhdpi" "mipmap-xxxhdpi") + + for dir in "${mipmap_dirs[@]}"; do + if [ ! -f "android/app/src/main/res/$dir/ic_launcher.png" ]; then + missing_mipmaps+=("$dir/ic_launcher.png") + fi + if [ ! -f "android/app/src/main/res/$dir/ic_launcher_round.png" ]; then + missing_mipmaps+=("$dir/ic_launcher_round.png") + fi + done + + # If any resources are missing, regenerate them + if [ ${#missing_drawables[@]} -gt 0 ] || [ ${#missing_mipmaps[@]} -gt 0 ]; then + log_warn "Missing Android resources detected:" + for resource in "${missing_drawables[@]}" "${missing_mipmaps[@]}"; do + log_warn " - $resource" + done + + log_info "Regenerating Android assets..." + + # Create assets directory if it doesn't exist + mkdir -p assets + + # Copy source assets to assets directory for capacitor-assets + cp resources/icon.png assets/ 2>/dev/null || log_warn "Could not copy icon.png" + cp resources/splash.png assets/ 2>/dev/null || log_warn "Could not copy splash.png" + cp resources/splash_dark.png assets/ 2>/dev/null || log_warn "Could not copy splash_dark.png" + + # Generate assets + if npx @capacitor/assets generate >/dev/null 2>&1; then + log_success "Android assets regenerated successfully" + + # Clean up temporary assets + rm -f assets/icon.png assets/splash.png assets/splash_dark.png + + # Verify the resources were created + local verification_failed=false + + if [ ! -f "android/app/src/main/res/drawable/splash.png" ]; then + log_error "Failed to generate drawable/splash.png" + verification_failed=true + fi + + for dir in "${mipmap_dirs[@]}"; do + if [ ! -f "android/app/src/main/res/$dir/ic_launcher.png" ]; then + log_error "Failed to generate $dir/ic_launcher.png" + verification_failed=true + fi + if [ ! -f "android/app/src/main/res/$dir/ic_launcher_round.png" ]; then + log_error "Failed to generate $dir/ic_launcher_round.png" + verification_failed=true + fi + done + + if [ "$verification_failed" = true ]; then + log_error "Asset generation completed but some resources are still missing." + log_info "You may need to manually create the missing resources or check the asset generation process." + return 1 + fi + else + log_error "Failed to generate Android assets" + log_info "You may need to manually create the missing resources:" + for resource in "${missing_drawables[@]}" "${missing_mipmaps[@]}"; do + log_info " - android/app/src/main/res/$resource" + done + return 1 + fi + else + log_success "All Android assets and resources validated successfully" + fi + + return 0 +} + # Default values BUILD_MODE="development" BUILD_TYPE="debug" @@ -126,7 +237,7 @@ parse_android_args() { --sync) SYNC_ONLY=true ;; - --assets) + --assets|--assets-only) ASSETS_ONLY=true ;; --deploy) @@ -208,6 +319,12 @@ print_header "TimeSafari Android Build Process" # Validate dependencies before proceeding validate_dependencies +# Validate Android assets and resources +validate_android_assets || { + log_error "Android asset validation failed. Please fix the issues above and try again." + exit 9 +} + # Log build start log_info "Starting Android build process at $(date)" log_info "Build mode: $BUILD_MODE" diff --git a/scripts/build-arch-guard.sh b/scripts/build-arch-guard.sh index 77a69ae7..f61fa8d1 100755 --- a/scripts/build-arch-guard.sh +++ b/scripts/build-arch-guard.sh @@ -3,8 +3,10 @@ # Build Architecture Guard Script # # Author: Matthew Raymer -# Date: 2025-08-20 +# Date: 2025-08-22 # Purpose: Protects build-critical files by requiring BUILDING.md updates +# Enhanced to protect Android build system including asset validation, +# API routing, and resource generation logic # # Usage: # ./scripts/build-arch-guard.sh --staged # Check staged files (pre-commit) @@ -26,14 +28,19 @@ SENSITIVE=( "Dockerfile" "docker/**" "capacitor.config.ts" + "capacitor-assets.config.json" # Critical for Android assets "package.json" "package-lock.json" "yarn.lock" "pnpm-lock.yaml" + "resources/**" # Source assets for Android ) # Documentation files that must be updated alongside sensitive changes -DOCS_REQUIRED=("BUILDING.md") +DOCS_REQUIRED=( + "BUILDING.md" + "doc/README-BUILD-GUARD.md" # Guard documentation +) # Colors for output RED='\033[0;31m' @@ -103,6 +110,137 @@ check_docs_updated() { return 1 } +# Check if Android build system was modified +check_android_build_changes() { + local changed_files=("$@") + + for file in "${changed_files[@]}"; do + if [[ "$file" =~ ^android/ ]] || [[ "$file" =~ ^scripts/build-android\.sh$ ]]; then + return 0 + fi + done + return 1 +} + +# Check if asset configuration was modified +check_asset_config_changes() { + local changed_files=("$@") + + for file in "${changed_files[@]}"; do + if [[ "$file" =~ ^capacitor-assets\.config\.json$ ]] || [[ "$file" =~ ^resources/ ]]; then + return 0 + fi + done + return 1 +} + +# Enhanced validation for Android changes +validate_android_changes() { + local changed_files=("$@") + + if check_android_build_changes "${changed_files[@]}"; then + log_warn "Android build system changes detected!" + echo + echo "Android build system changes require enhanced validation:" + echo " - Test asset generation: npm run build:android --assets" + echo " - Test API routing modes: --dev and --dev --api-ip <custom>" + echo " - Verify resource fallback mechanisms" + echo " - Test across development/test/production modes" + echo + echo "Please ensure BUILDING.md includes Android-specific testing procedures." + echo + fi + + if check_asset_config_changes "${changed_files[@]}"; then + log_warn "Asset configuration changes detected!" + echo + echo "Asset configuration changes require validation:" + echo " - Test asset generation across all platforms" + echo " - Verify resource files are properly created" + echo " - Test asset validation scripts" + echo + fi +} + +# Feedback collection for continuous improvement +collect_feedback_data() { + local mode="$1" + local sensitive_touched=("${@:2}") + local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") + + # Create feedback log entry + local feedback_log=".guard-feedback.log" + echo "[$timestamp] Guard execution: $mode" >> "$feedback_log" + echo " Sensitive files: ${sensitive_touched[*]}" >> "$feedback_log" + + # Log Android-specific changes for analysis + if check_android_build_changes "${sensitive_touched[@]}"; then + echo " Android changes detected" >> "$feedback_log" + fi + + # Log asset configuration changes for analysis + if check_asset_config_changes "${sensitive_touched[@]}"; then + echo " Asset config changes detected" >> "$feedback_log" + fi + + echo "" >> "$feedback_log" +} + +# Enhanced error handling with Android-specific guidance +handle_documentation_error() { + local sensitive_touched=("$@") + + log_error "Build-sensitive files changed but BUILDING.md was not updated!" + echo + echo "The following build-sensitive files were modified:" + for file in "${sensitive_touched[@]}"; do + echo " - $file" + done + echo + echo "When modifying build-critical files, you must also update BUILDING.md" + echo "to document any changes to the build process." + echo + + # Add Android-specific guidance + if check_android_build_changes "${sensitive_touched[@]}"; then + echo "⚠️ ANDROID BUILD SYSTEM CHANGES DETECTED ⚠️" + echo "Android changes require enhanced documentation including:" + echo " - Asset validation procedures" + echo " - API routing configuration" + echo " - Resource generation testing" + echo " - Platform-specific build modes" + echo + fi + + if check_asset_config_changes "${sensitive_touched[@]}"; then + echo "🎨 ASSET CONFIGURATION CHANGES DETECTED 🎨" + echo "Asset changes require documentation including:" + echo " - Asset generation procedures" + echo " - Resource validation steps" + echo " - Platform-specific asset requirements" + echo + fi + + echo "Please:" + echo " 1. Update BUILDING.md with relevant changes" + echo " 2. Stage the BUILDING.md changes: git add BUILDING.md" + echo " 3. Retry your commit/push" + echo + echo "💡 Feedback: If this guard is too strict or missing patterns," + echo " please report to the development team for continuous improvement." + echo + echo "📊 Feedback Categories:" + echo " - False positives (files flagged that shouldn't be)" + echo " - False negatives (sensitive files not caught)" + echo " - Missing patterns (new file types to protect)" + echo " - Overly strict (patterns too restrictive)" + echo " - Documentation gaps (missing guidance)" + echo " - Testing improvements (better procedures)" + echo + echo "📝 Report feedback to: Development team with specific examples" + echo +} + # Main guard logic main() { local mode="${1:-}" @@ -111,7 +249,10 @@ main() { log_info "Running Build Architecture Guard..." # Collect changed files - mapfile -t changed_files < <(collect_files "$mode" "$arg") + changed_files=() + while IFS= read -r line; do + [[ -n "$line" ]] && changed_files+=("$line") + done < <(collect_files "$mode" "$arg") if [[ ${#changed_files[@]} -eq 0 ]]; then log_info "No files changed, guard check passed" @@ -140,26 +281,19 @@ main() { echo " - $file" done + # Enhanced validation for Android changes + validate_android_changes "${changed_files[@]}" + + # Collect feedback data for continuous improvement + collect_feedback_data "$mode" "${sensitive_touched[@]}" + # Check if required documentation was updated if check_docs_updated "${changed_files[@]}"; then log_success "BUILDING.md updated alongside build changes, guard check passed" exit 0 else - log_error "Build-sensitive files changed but BUILDING.md was not updated!" - echo - echo "The following build-sensitive files were modified:" - for file in "${sensitive_touched[@]}"; do - echo " - $file" - done - echo - echo "When modifying build-critical files, you must also update BUILDING.md" - echo "to document any changes to the build process." - echo - echo "Please:" - echo " 1. Update BUILDING.md with relevant changes" - echo " 2. Stage the BUILDING.md changes: git add BUILDING.md" - echo " 3. Retry your commit/push" - echo + # Enhanced error handling with Android-specific guidance + handle_documentation_error "${sensitive_touched[@]}" exit 2 fi } @@ -176,11 +310,45 @@ if [[ "${1:-}" =~ ^(-h|--help)$ ]]; then echo " --range [RANGE] Check git range (for pre-push hook)" echo " Default range: HEAD~1..HEAD" echo " (no args) Check working directory changes" + echo " --feedback Show feedback analysis (for maintainers)" echo echo "Examples:" echo " $0 --staged # Pre-commit check" echo " $0 --range origin/main..HEAD # Pre-push check" echo " $0 # Working directory check" + echo " $0 --feedback # Analyze guard effectiveness" + exit 0 +fi + +# Handle feedback analysis +if [[ "${1:-}" == "--feedback" ]]; then + if [[ -f ".guard-feedback.log" ]]; then + echo "Build Architecture Guard Feedback Analysis" + echo "==========================================" + echo + echo "Recent guard executions:" + echo + tail -20 ".guard-feedback.log" | while IFS= read -r line; do + if [[ "$line" =~ ^\[ ]]; then + echo "📅 $line" + elif [[ "$line" =~ ^\s*Sensitive\ files: ]]; then + echo "🔍 $line" + elif [[ "$line" =~ ^\s*Android\ changes ]]; then + echo "🤖 $line" + elif [[ "$line" =~ ^\s*Asset\ config ]]; then + echo "🎨 $line" + elif [[ "$line" =~ ^\s*$ ]]; then + echo "" + else + echo " $line" + fi + done + echo + echo "💡 Use this data to improve guard patterns and documentation" + echo "📊 Total executions: $(grep -c "Guard execution" .guard-feedback.log 2>/dev/null || echo "0")" + else + echo "No feedback data available yet. Run the guard to collect data." + fi exit 0 fi diff --git a/src/libs/endorserServer.ts b/src/libs/endorserServer.ts index 735252f7..a543ea8d 100644 --- a/src/libs/endorserServer.ts +++ b/src/libs/endorserServer.ts @@ -309,7 +309,7 @@ export function didInfoForContact( showDidForVisible: boolean = false, // eslint-disable-next-line @typescript-eslint/no-explicit-any ): { known: boolean; displayName: string; profileImageUrl?: string } { - if (!did) return { displayName: "Someone Unnamed/Unknown", known: false }; + if (!did) return { displayName: "Someone Not Named", known: false }; if (did === activeDid) { return { displayName: "You", known: true }; } else if (contact) { diff --git a/src/libs/util.ts b/src/libs/util.ts index c65f2f8a..e21d1932 100644 --- a/src/libs/util.ts +++ b/src/libs/util.ts @@ -657,7 +657,7 @@ export async function saveNewIdentity( await platformService.updateDefaultSettings({ activeDid: identity.did }); - await platformService.insertDidSpecificSettings(identity.did); + await platformService.insertNewDidIntoSettings(identity.did); } catch (error) { logger.error("Failed to update default settings:", error); throw new Error( @@ -954,7 +954,7 @@ export async function importFromMnemonic( try { // First, ensure the DID-specific settings record exists - await platformService.insertDidSpecificSettings(newId.did); + await platformService.insertNewDidIntoSettings(newId.did); // Then update with Test User #0 specific settings await platformService.updateDidSpecificSettings(newId.did, { diff --git a/src/services/PlatformService.ts b/src/services/PlatformService.ts index a3dbff6a..ede6a5b0 100644 --- a/src/services/PlatformService.ts +++ b/src/services/PlatformService.ts @@ -175,11 +175,11 @@ export interface PlatformService { updateDefaultSettings(settings: Record<string, unknown>): Promise<void>; /** - * Inserts DID-specific settings into the database. + * Inserts a new DID into the settings table. * @param did - The DID to associate with the settings * @returns Promise that resolves when the insertion is complete */ - insertDidSpecificSettings(did: string): Promise<void>; + insertNewDidIntoSettings(did: string): Promise<void>; /** * Updates DID-specific settings in the database. diff --git a/src/services/platforms/CapacitorPlatformService.ts b/src/services/platforms/CapacitorPlatformService.ts index bd22ef8d..c1374f25 100644 --- a/src/services/platforms/CapacitorPlatformService.ts +++ b/src/services/platforms/CapacitorPlatformService.ts @@ -1319,7 +1319,7 @@ export class CapacitorPlatformService implements PlatformService { await this.dbExec(sql, params); } - async insertDidSpecificSettings(did: string): Promise<void> { + async insertNewDidIntoSettings(did: string): Promise<void> { await this.dbExec("INSERT INTO settings (accountDid) VALUES (?)", [did]); } diff --git a/src/services/platforms/WebPlatformService.ts b/src/services/platforms/WebPlatformService.ts index a731ee22..fb15b1b6 100644 --- a/src/services/platforms/WebPlatformService.ts +++ b/src/services/platforms/WebPlatformService.ts @@ -681,7 +681,7 @@ export class WebPlatformService implements PlatformService { await this.dbExec(sql, params); } - async insertDidSpecificSettings(did: string): Promise<void> { + async insertNewDidIntoSettings(did: string): Promise<void> { await this.dbExec("INSERT INTO settings (accountDid) VALUES (?)", [did]); } diff --git a/src/test/index.ts b/src/test/index.ts index 0e92c6f8..914cb2be 100644 --- a/src/test/index.ts +++ b/src/test/index.ts @@ -50,6 +50,10 @@ export async function testServerRegisterUser() { "@/db/databaseUtil" ); const settings = await retrieveSettingsForActiveAccount(); + const currentDid = settings?.activeDid; + if (!currentDid) { + throw new Error("No active DID found"); + } // Make a claim const vcClaim = { @@ -57,7 +61,7 @@ export async function testServerRegisterUser() { "@type": "RegisterAction", agent: { identifier: identity0.did }, object: SERVICE_ID, - participant: { identifier: settings.activeDid }, + participant: { identifier: currentDid }, }; // Make a payload for the claim @@ -94,5 +98,12 @@ export async function testServerRegisterUser() { const resp = await axios.post(url, payload, { headers }); logger.log("User registration result:", resp); + + const platformService = await PlatformServiceFactory.getInstance(); + await platformService.updateDefaultSettings({ activeDid: currentDid }); + await platformService.updateDidSpecificSettings(currentDid!, { + isRegistered: true, + }); + return resp; } diff --git a/src/views/ContactGiftingView.vue b/src/views/ContactGiftingView.vue index 91d10c9c..403a1fbe 100644 --- a/src/views/ContactGiftingView.vue +++ b/src/views/ContactGiftingView.vue @@ -24,7 +24,7 @@ icon="circle-question" class="text-slate-400 text-4xl" /> - <span class="italic text-slate-400">(Unnamed/Unknown)</span> + <span class="italic text-slate-400">(Not Named)</span> </span> <span class="text-right"> <button diff --git a/src/views/HelpView.vue b/src/views/HelpView.vue index fff71f21..a3668db1 100644 --- a/src/views/HelpView.vue +++ b/src/views/HelpView.vue @@ -18,6 +18,7 @@ <!-- Heading --> <h1 id="ViewHeading" class="text-4xl text-center font-light pt-4 mb-8"> Help + <span class="text-xs text-gray-500">{{ package.version }}</span> </h1> </div>