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
This commit is contained in:
Matthew Raymer
224
.cursor/rules/architecture/build_validation.mdc
Normal file
224
.cursor/rules/architecture/build_validation.mdc
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user