eff7e339af
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
225 lines
5.9 KiB
Plaintext
225 lines
5.9 KiB
Plaintext
# 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
|