refactor(cursor-rules): restructure rules architecture with meta-rule system

- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories
2025-08-23 13:04:09 +00:00
parent b9ca59a718
commit a224aced85
61 changed files with 8944 additions and 2847 deletions
--- 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
--- a/.cursor/rules/database/legacy_dexie.mdc
+++ b/.cursor/rules/database/legacy_dexie.mdc
@@ -1,8 +1,62 @@
---
-globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue
-alwaysApply: false
---
-# What to do with Dexie
+# Legacy Dexie Database — Migration Guidelines

-All references in the codebase to Dexie apply only to migration from IndexedDb to
-Sqlite and will be deprecated in future versions.
+> **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
+
+---
+
+**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