diff --git a/BUILDING.md b/BUILDING.md index e5abf069..17c367d6 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -13,7 +13,7 @@ npm run build:web:serve -- --test # Start with test endorser server npm run build:web:dev # Start development server with hot reload with local endorser server npm run build:web:prod # Production build -# 📱 Mobile Development +# 📱 Mobile Development npm run build:ios # iOS build (opens Xcode) npm run build:android # Android build (opens Android Studio) @@ -31,6 +31,7 @@ npm run clean:all # Clean all platforms ### Development Workflow #### 1. First-Time Setup + ```bash # Install dependencies npm install @@ -40,6 +41,7 @@ npm run test:web # Run web tests to verify setup ``` #### 2. Daily Development + ```bash # Start web development server npm run build:web:dev # Opens http://localhost:8080 @@ -48,11 +50,12 @@ npm run build:web:dev # Opens http://localhost:8080 npm run build:ios # Opens Xcode with iOS project npm run build:android # Opens Android Studio with Android project -# For desktop development +# For desktop development npm run build:electron:dev # Runs Electron app directly ``` #### 3. Testing Your Changes + ```bash # Test web functionality npm run test:web # Run web tests @@ -66,6 +69,7 @@ npm run build:android:test:run # Build and run on Android emulator ``` #### 4. Production Builds + ```bash # Build for production npm run build:web:prod # Web production build @@ -77,6 +81,7 @@ npm run build:electron:prod # Electron production build ### Environment Configuration #### Quick Environment Setup + ```bash # Copy environment template (if available) cp .env.example .env.development @@ -89,6 +94,7 @@ cp .env.example .env.development ``` #### Platform-Specific Development + - **Web**: Uses `localhost:3000` for APIs by default - **iOS Simulator**: Uses `localhost:3000` for APIs - **Android Emulator**: Uses `10.0.2.2:3000` for APIs @@ -97,6 +103,7 @@ cp .env.example .env.development ### Troubleshooting Quick Fixes #### Common Issues + ```bash # Clean and rebuild npm run clean:all @@ -114,6 +121,7 @@ npm run test:web # Verifies web setup ``` #### Platform-Specific Issues + - **iOS**: Ensure Xcode and Command Line Tools are installed - **Android**: Ensure Android Studio and SDK are configured - **Electron**: Ensure platform-specific build tools are installed @@ -222,6 +230,7 @@ All web build commands use the `./scripts/build-web.sh` script, which provides: ``` **Script Flow:** + 1. **Environment Validation**: Check prerequisites (Node.js, npm, etc.) 2. **Environment Setup**: Load `.env` files, set NODE_ENV 3. **Clean Dist**: Remove previous build artifacts @@ -230,8 +239,9 @@ All web build commands use the `./scripts/build-web.sh` script, which provides: 6. **Optional Serve**: Start local HTTP server if requested **Exit Codes:** + - `1` - Web cleanup failed -- `2` - Environment setup failed +- `2` - Environment setup failed - `3` - Vite build failed - `4` - Docker build failed - `5` - Serve command failed @@ -239,19 +249,25 @@ All web build commands use the `./scripts/build-web.sh` script, which provides: ### Compile and minify for test & production -* If there are DB changes: before updating the test server, open browser(s) with current version to test DB migrations. +- If there are DB changes: before updating the test server, open browser(s) with +current version to test DB migrations. -* Update the ClickUp tasks & CHANGELOG.md & the version in package.json, run `npm install`. +- Update the ClickUp tasks & CHANGELOG.md & the version in package.json, run +`npm install`. -* Run a build to make sure package-lock version is updated, linting works, etc: `npm install && npm run build:web` +- Run a build to make sure package-lock version is updated, linting works, etc: +`npm install && npm run build:web` -* Commit everything (since the commit hash is used the app). +- Commit everything (since the commit hash is used the app). -* Put the commit hash in the changelog (which will help you remember to bump the version in the step later). +- Put the commit hash in the changelog (which will help you remember to bump the + version in the step later). -* Tag with the new version, [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`. +- Tag with the new version, +[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 (because test server is not yet set up to build): ```bash TIME_SAFARI_APP_TITLE="TimeSafari_Test" \ @@ -274,25 +290,28 @@ rsync -azvu -e "ssh -i ~/.ssh/..." dist ubuntutest@test.timesafari.app:time-safa (Note: The test BVC_MEETUPS_PROJECT_CLAIM_ID does not resolve as a URL because it's only in the test DB and the prod redirect won't redirect there.) -* For prod, get on the server and run the correct build: +- For prod, get on the server and run the correct build: ... and log onto the server: -* `pkgx +npm sh` +- `pkgx +npm sh` -* `cd crowd-funder-for-time-pwa && git checkout master && git pull && git checkout 1.0.2 && npm install && npm run build:web:prod && cd -` +- `cd crowd-funder-for-time-pwa && git checkout master && git pull && git checkout +1.0.2 && npm install && npm run build:web:prod && cd -` (The plain `npm run build:web:prod` uses the .env.production file.) -* Back up the time-safari/dist folder & deploy: `mv time-safari/dist time-safari-dist-prev-2 && mv crowd-funder-for-time-pwa/dist time-safari/` +- Back up the time-safari/dist folder & deploy: `mv time-safari/dist time-safari-dist-prev-2 && mv crowd-funder-for-time-pwa/dist time-safari/` -* Record the new hash in the changelog. Edit package.json to increment version & add "-beta", `npm install`, commit, and push. Also record what version is on production. +- Record the new hash in the changelog. Edit package.json to increment version & +add "-beta", `npm install`, commit, and push. Also record what version is on production. ## Docker Deployment -The application can be containerized using Docker for consistent deployment across environments. +The application can be containerized using Docker for consistent deployment across +environments. -### Prerequisites +### Docker Prerequisites - Docker installed on your system - Docker Compose (optional, for multi-container setups) @@ -402,7 +421,10 @@ docker run -d \ ## Desktop Build (Electron) -TimeSafari's Electron build system provides comprehensive desktop application packaging and distribution capabilities across Windows, macOS, and Linux platforms. The system supports multiple build modes, environment configurations, and package formats. +TimeSafari's Electron build system provides comprehensive desktop application +packaging and distribution capabilities across Windows, macOS, and Linux +platforms. The system supports multiple build modes, environment configurations, +and package formats. ### Electron Build Commands @@ -436,15 +458,18 @@ npm run clean:electron # Clean Electron build artifacts #### Development Build -Start development build using `npm run build:electron:dev` (builds and runs the app directly). +Start development build using `npm run build:electron:dev` (builds and runs the +app directly). #### Production Build -Run production builds using the commands above. Production builds create platform-specific packages. +Run production builds using the commands above. Production builds create +platform-specific packages. #### Package-Specific Builds -Create platform-specific packages using the commands above. These build the app and create installable packages. +Create platform-specific packages using the commands above. These build the app +and create installable packages. ### Single Instance Enforcement @@ -484,29 +509,29 @@ The Electron app enforces single-instance operation to prevent: The Electron build process follows a multi-stage approach: -``` +```text 1. Web Build (Vite) → 2. Capacitor Sync → 3. TypeScript Compile → 4. Package ``` -**Stage 1: Web Build** +#### **Stage 1: Web Build** - Vite builds web assets with Electron-specific configuration - Environment variables loaded based on build mode - Assets optimized for desktop application -**Stage 2: Capacitor Sync** +#### **Stage 2: Capacitor Sync** - Copies web assets to Electron app directory - Syncs Capacitor configuration and plugins - Prepares native module bindings -**Stage 3: TypeScript Compile** +#### **Stage 3: TypeScript Compile** - Compiles Electron main process TypeScript - Rebuilds native modules for target platform - Generates production-ready JavaScript -**Stage 4: Package Creation** +#### **Stage 4: Package Creation** - Creates platform-specific installers - Generates distribution packages @@ -566,6 +591,7 @@ npm run build:electron:windows:prod ``` **Configuration**: + - NSIS installer with custom options - Desktop and Start Menu shortcuts - Elevation permissions for installation @@ -588,6 +614,7 @@ npm run build:electron:mac:prod ``` **Configuration**: + - Universal binary (x64 + arm64) - DMG installer with custom branding - App Store compliance (when configured) @@ -610,12 +637,13 @@ npm run build:electron:linux:prod ``` **Configuration**: + - AppImage for universal distribution - DEB package for Debian-based systems - RPM package for Red Hat-based systems - Desktop integration -### Package-Specific Builds +### Desktop Package-Specific Builds #### AppImage Package @@ -634,6 +662,7 @@ npm run build:electron:appimage:prod ``` **Features**: + - Single file distribution - No installation required - Portable across Linux distributions @@ -656,6 +685,7 @@ npm run build:electron:deb:prod ``` **Features**: + - Native package management - Dependency resolution - System integration @@ -678,6 +708,7 @@ npm run build:electron:dmg:prod ``` **Features**: + - Native macOS installer - Custom branding and layout - Drag-and-drop installation @@ -742,7 +773,7 @@ npm run build:electron:dmg:test # DMG test build npm run build:electron:dmg:prod # DMG production build ``` -#### Direct Script Usage +#### Direct Script Usage Reference All npm scripts use the underlying `./scripts/build-electron.sh` script: @@ -766,9 +797,9 @@ npm run clean:electron # Clean Electron build artifacts ### Build Output Structure -#### Development Build +#### Development Build Structure -``` +```text electron/ ├── app/ # Web assets ├── build/ # Compiled TypeScript @@ -776,9 +807,9 @@ electron/ └── node_modules/ # Dependencies ``` -#### Production Build +#### Production Build Output -``` +```text electron/ ├── app/ # Web assets ├── build/ # Compiled TypeScript @@ -796,7 +827,8 @@ electron/ For public distribution on macOS, you need to code sign and notarize your app: -1. Set up environment variables: +##### 1. Set up environment variables + ```bash export CSC_LINK=/path/to/your/certificate.p12 export CSC_KEY_PASSWORD=your_certificate_password @@ -804,7 +836,8 @@ export APPLE_ID=your_apple_id export APPLE_ID_PASSWORD=your_app_specific_password ``` -2. Build with signing: +##### 2. Build with signing + ```bash npm run build:electron:mac:prod ``` @@ -813,13 +846,15 @@ npm run build:electron:mac:prod For Windows distribution, configure Authenticode signing: -1. Set up environment variables: +##### 1. Set up desktop environment variables + ```bash export CSC_LINK=/path/to/your/certificate.p12 export CSC_KEY_PASSWORD=your_certificate_password ``` -2. Build with signing: +##### 2. Build desktop with signing + ```bash npm run build:electron:windows:prod ``` @@ -829,12 +864,14 @@ npm run build:electron:windows:prod #### Linux - **AppImage**: Make executable and run + ```bash chmod +x electron/dist/TimeSafari-*.AppImage ./electron/dist/TimeSafari-*.AppImage ``` - **DEB**: Install and run + ```bash sudo dpkg -i electron/dist/timesafari_*_amd64.deb timesafari @@ -849,6 +886,7 @@ timesafari 3. Launch from Applications Note: If you get a security warning when running the app: + 1. Right-click the app 2. Select "Open" 3. Click "Open" in the security dialog @@ -863,6 +901,7 @@ Note: If you get a security warning when running the app: #### Common Build Issues **TypeScript Compilation Errors**: + ```bash # Clean and rebuild npm run clean:electron @@ -870,30 +909,35 @@ npm run build:electron:dev ``` **Native Module Issues**: + ```bash # Rebuild native modules npm run build:electron:dev ``` **Asset Copy Issues**: + ```bash # Verify Capacitor sync npx cap sync electron ``` -#### Platform-Specific Issues +#### Platform-Specific Building Issues **Windows**: + - Ensure Windows Build Tools installed - Check NSIS installation - Verify code signing certificates **macOS**: + - Install Xcode Command Line Tools - Configure code signing certificates - Check app notarization requirements **Linux**: + - Install required packages (rpm-tools, etc.) - Check AppImage dependencies - Verify desktop integration @@ -984,6 +1028,7 @@ The recommended way to build for iOS is using the automated build script: ``` The script handles all the necessary steps including: + - Environment setup and validation - Web asset building (Capacitor mode) - Capacitor synchronization @@ -1004,11 +1049,11 @@ If you need to build manually or want to understand the individual steps: #### Each Release -0. First time (or if dependencies change): +##### 0. First time (or if dependencies change) - - `pkgx +rubygems.org sh` +- `pkgx +rubygems.org sh` - - ... and you may have to fix these, especially with pkgx: +- ... and you may have to fix these, especially with pkgx: ```bash gem_path=$(which gem) @@ -1017,15 +1062,15 @@ If you need to build manually or want to understand the individual steps: export GEM_PATH=$shortened_path ``` -1. Bump the version in package.json, then here. +##### 1. Bump the version in package.json, then here - ``` + ```bash cd ios/App && xcrun agvtool new-version 40 && perl -p -i -e "s/MARKETING_VERSION = .*;/MARKETING_VERSION = 1.0.7;/g" App.xcodeproj/project.pbxproj && cd - # Unfortunately this edits Info.plist directly. #xcrun agvtool new-marketing-version 0.4.5 ``` -2. Build. +##### 2. Build Here's prod. Also available: test, dev @@ -1035,22 +1080,28 @@ If you need to build manually or want to understand the individual steps: 3.1. Use Xcode to build and run on simulator or device. - * Select Product -> Destination with some Simulator version. Then click the run arrow. +- Select Product -> Destination with some Simulator version. Then click the run arrow. 3.2. Use Xcode to release. - * Someday: Under "General" we want to rename a bunch of things to "Time Safari" - * Choose Product -> Destination -> Any iOS Device - * Choose Product -> Archive - * This will trigger a build and take time, needing user's "login" keychain password (user's login password), repeatedly. - * If it fails with `building for 'iOS', but linking in dylib (.../.pkgx/zlib.net/v1.3.0/lib/libz.1.3.dylib) built for 'macOS'` then run XCode outside that terminal (ie. not with `npx cap open ios`). - * Click Distribute -> App Store Connect - * In AppStoreConnect, add the build to the distribution. You may have to remove the current build with the "-" when you hover over it, then "Add Build" with the new build. - * May have to go to App Review, click Submission, then hover over the build and click "-". - * It can take 15 minutes for the build to show up in the list of builds. - * You'll probably have to "Manage" something about encryption, disallowed in France. - * Then "Save" and "Add to Review" and "Resubmit to App Review". - * Eventually it'll be "Ready for Distribution" which means +- Someday: Under "General" we want to rename a bunch of things to "Time Safari" +- Choose Product -> Destination -> Any iOS Device +- Choose Product -> Archive + - This will trigger a build and take time, needing user's "login" keychain + password (user's login password), repeatedly. + - If it fails with `building for 'iOS', but linking in dylib + (.../.pkgx/zlib.net/v1.3.0/lib/libz.1.3.dylib) built for 'macOS'` then run + XCode outside that terminal (ie. not with `npx cap open ios`). + - Click Distribute -> App Store Connect +- In AppStoreConnect, add the build to the distribution. You may have to remove + the current build with the "-" when you hover over it, then "Add Build" with the + new build. + - May have to go to App Review, click Submission, then hover over the build + and click "-". + - It can take 15 minutes for the build to show up in the list of builds. + - You'll probably have to "Manage" something about encryption, disallowed in France. + - Then "Save" and "Add to Review" and "Resubmit to App Review". +- Eventually it'll be "Ready for Distribution" which means ### Android Build @@ -1063,7 +1114,7 @@ Prerequisites: Android Studio with Java SDK installed npm run build:android # Development build (builds and opens Android Studio) npm run build:android:dev # Development build (builds and opens Android Studio) npm run build:android:test # Test build (builds for testing environment) -npm run build:android:prod # Production build (builds for production environment) +npm run build:android:prod # Production build (builds for production environment). # Auto-run builds npm run build:android:test:run # Test build with auto-run (builds then runs on emulator) @@ -1085,7 +1136,7 @@ npm run build:android:assets # Generate assets only npm run build:android:deploy # Build and deploy to connected device ``` -#### Automated Build Script +#### Android Automated Build Script The recommended way to build for Android is using the automated build script: @@ -1103,16 +1154,16 @@ The recommended way to build for Android is using the automated build script: ./scripts/build-android.sh --help ``` -#### Manual Build Process +#### Android Manual Build Process -1. Bump the version in package.json, then here: android/app/build.gradle +##### 1. Bump the version in package.json, then here: android/app/build.gradle ```bash perl -p -i -e 's/versionCode .*/versionCode 40/g' android/app/build.gradle perl -p -i -e 's/versionName .*/versionName "1.0.7"/g' android/app/build.gradle ``` -2. Build. +##### 2. Build Here's prod. Also available: test, dev @@ -1120,13 +1171,13 @@ The recommended way to build for Android is using the automated build script: npm run build:android:prod ``` -3. Open the project in Android Studio: +##### 3. Open the project in Android Studio ```bash npx cap open android ``` -4. Use Android Studio to build and run on emulator or device. +##### 4. Use Android Studio to build and run on emulator or device ## Android Build from the console @@ -1145,9 +1196,10 @@ cd - ... or, to create a signed release: -* Setup by adding the app/gradle.properties.secrets file (see properties at top of app/build.gradle) and the app/time-safari-upload-key-pkcs12.jks file -* In app/build.gradle, bump the versionCode and maybe the versionName -* Then `bundleRelease`: +- Setup by adding the app/gradle.properties.secrets file (see properties at top + of app/build.gradle) and the app/time-safari-upload-key-pkcs12.jks file +- In app/build.gradle, bump the versionCode and maybe the versionName +- Then `bundleRelease`: ```bash cd android @@ -1165,7 +1217,8 @@ At play.google.com/console: - Hit "Next". - Save, go to "Publishing Overview" as prompted, and click "Send changes for review". -- Note that if you add testers, you have to go to "Publishing Overview" and send those changes or your (closed) testers won't see it. +- Note that if you add testers, you have to go to "Publishing Overview" and send + those changes or your (closed) testers won't see it. ### Capacitor Operations @@ -1263,7 +1316,7 @@ npm run lint-fix # Fix linting issues Use the commands above to check and fix code quality issues. -## Build Architecture +## Code Build Architecture ### Web Build Process @@ -1288,19 +1341,22 @@ Use the commands above to check and fix code quality issues. 4. **Native Build**: Platform-specific compilation 5. **Package Creation**: APK/IPA generation -## Environment Configuration +## Architecture Environment Configuration ### Environment Files The build system supports multiple environment file patterns for different scenarios: #### Primary Environment Files + - `.env.development` - Development environment (local development) - `.env.test` - Testing environment (staging/testing) - `.env.production` - Production environment (production deployment) #### Fallback and Local Files -- `.env` - General fallback environment file (loaded if mode-specific file doesn't exist) + +- `.env` - General fallback environment file (loaded if mode-specific file + doesn't exist) - `.env.local` - Local development overrides (gitignored) - `.env.*.local` - Mode-specific local overrides (gitignored) @@ -1324,6 +1380,7 @@ The build system supports multiple environment file patterns for different scena ### Key Environment Variables #### API Server Configuration + ```bash # API Servers (Environment-specific) VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch @@ -1342,6 +1399,7 @@ VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZY #### Environment-Specific Configurations **Development Environment** (`.env.development`): + ```bash # Development API Servers (Local) VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000 @@ -1351,6 +1409,7 @@ VITE_APP_SERVER=http://localhost:8080 ``` **Test Environment** (`.env.test`): + ```bash # Test API Servers VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch @@ -1360,6 +1419,7 @@ VITE_APP_SERVER=https://test.timesafari.app ``` **Production Environment** (`.env.production`): + ```bash # Production API Servers VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch @@ -1371,16 +1431,19 @@ VITE_APP_SERVER=https://timesafari.app ### Platform-Specific Overrides #### Android Development + - **Emulator**: Uses `http://10.0.2.2:3000` (Android emulator default) - **Physical Device**: Uses custom IP address (e.g., `http://192.168.1.100:3000`) #### iOS Development + - **Simulator**: Uses `http://localhost:3000` (iOS simulator default) - **Physical Device**: Uses custom IP address (e.g., `http://192.168.1.100:3000`) ### Environment Loading Process 1. **Build Script Initialization** + ```bash # scripts/common.sh - setup_build_env() if [ "$BUILD_MODE" = "development" ]; then @@ -1390,6 +1453,7 @@ VITE_APP_SERVER=https://timesafari.app ``` 2. **Platform-Specific Overrides** + ```bash # scripts/build-android.sh if [ "$BUILD_MODE" = "development" ]; then @@ -1399,13 +1463,14 @@ VITE_APP_SERVER=https://timesafari.app ``` 3. **Environment File Loading** + ```bash # scripts/build-web.sh local env_file=".env.$BUILD_MODE" # .env.development, .env.test, .env.production if [ -f "$env_file" ]; then load_env_file "$env_file" fi - + # Fallback to .env if [ -f ".env" ]; then load_env_file ".env" @@ -1413,6 +1478,7 @@ VITE_APP_SERVER=https://timesafari.app ``` 4. **Application Usage** + ```typescript // src/constants/app.ts export const DEFAULT_ENDORSER_API_SERVER = @@ -1420,9 +1486,9 @@ VITE_APP_SERVER=https://timesafari.app AppString.PROD_ENDORSER_API_SERVER; ``` -## Troubleshooting +## Building Troubleshooting -### Common Issues +### Common Issues Building #### Build Failures @@ -1447,29 +1513,34 @@ npm run build:ios:assets npm run build:android:assets ``` -### Platform-Specific Issues +### More Platform-Specific Building Issues + +#### Building on Windows -#### Windows - Ensure Windows Build Tools installed - Check NSIS installation - Verify code signing certificates -#### macOS +#### Building on macOS + - Install Xcode Command Line Tools - Configure code signing certificates - Check app notarization requirements -#### Linux +#### Building on Linux + - Install required packages (rpm-tools, etc.) - Check AppImage dependencies - Verify desktop integration #### iOS + - Install Xcode and Command Line Tools - Configure signing certificates - Check provisioning profiles #### Android + - Install Android Studio and SDK - Configure signing keys - Check device/emulator setup @@ -1488,37 +1559,45 @@ npm run build:android:assets ### Build Process Overview -TimeSafari's build system follows a multi-stage process that prepares assets, combines scripts, and generates platform-specific outputs. +TimeSafari's build system follows a multi-stage process that prepares assets, +combines scripts, and generates platform-specific outputs. #### Pre-Build Preparation -**1. Service Worker Script Preparation** +##### 1. Service Worker Script Preparation + ```bash # Optional: Format third-party service worker scripts npx prettier --write ./sw_scripts/ ``` **What this does:** -- Formats cryptographic libraries (`nacl.js`, `noble-curves.js`, `noble-hashes.js`, etc.) + +- Formats cryptographic libraries (`nacl.js`, `noble-curves.js`, + `noble-hashes.js`, etc.) - These scripts are automatically combined during the build process - Improves readability and makes version control diffs cleaner - **Note**: This is optional and only needed when updating third-party scripts **2. Automatic Pre-Build Steps** The `prebuild` script automatically runs before any build: + ```json "prebuild": "eslint --ext .js,.ts,.vue --ignore-path .gitignore src && node sw_combine.js && node scripts/copy-wasm.js" ``` **What happens automatically:** + - **ESLint**: Checks and fixes code formatting in `src/` -- **Script Combination**: `sw_combine.js` combines all `sw_scripts/*.js` files into `sw_scripts-combined.js` +- **Script Combination**: `sw_combine.js` combines all `sw_scripts/*.js` files + into `sw_scripts-combined.js` - **WASM Copy**: `copy-wasm.js` copies SQLite WASM files to `public/wasm/` -#### Build Architecture +#### Build Process Architecture **Web Build Process:** -``` + +```text 1. Pre-Build: ESLint + Script Combination + WASM Copy 2. Environment Setup: Load .env files, set NODE_ENV 3. Vite Build: Bundle web assets with PWA support @@ -1527,7 +1606,8 @@ The `prebuild` script automatically runs before any build: ``` **Electron Build Process:** -``` + +```text 1. Web Build: Vite builds web assets for Electron 2. Capacitor Sync: Copies assets to Electron app directory 3. TypeScript Compile: Compiles main process code @@ -1536,7 +1616,8 @@ The `prebuild` script automatically runs before any build: ``` **Mobile Build Process:** -``` + +```text 1. Web Build: Vite builds web assets 2. Capacitor Sync: Syncs with native platforms 3. Asset Generation: Creates platform-specific assets @@ -1547,12 +1628,14 @@ The `prebuild` script automatically runs before any build: #### Service Worker Architecture **Script Organization:** + - `sw_scripts/` - Individual third-party scripts - `sw_combine.js` - Combines scripts into single file - `sw_scripts-combined.js` - Combined service worker (317KB, 10K+ lines) - `vite.config.utils.mts` - PWA configuration using combined script **PWA Integration:** + ```typescript // vite.config.utils.mts pwaConfig: { @@ -1563,31 +1646,35 @@ pwaConfig: { ``` **What Gets Combined:** + - `nacl.js` - NaCl cryptographic library - `noble-curves.js` - Elliptic curve cryptography (177KB) - `noble-hashes.js` - Cryptographic hash functions (91KB) - `safari-notifications.js` - Safari-specific notifications - `additional-scripts.js` - Additional service worker functionality -#### Environment Configuration +#### Process Environment Configuration **Environment Files:** The build system supports multiple environment file patterns: - `.env.development` - Development environment (local development) -- `.env.test` - Testing environment (staging/testing) +- `.env.test` - Testing environment (staging/testing) - `.env.production` - Production environment (production deployment) -- `.env` - General fallback environment file (loaded if mode-specific file doesn't exist) +- `.env` - General fallback environment file (loaded if mode-specific file + doesn't exist) - `.env.local` - Local development overrides (gitignored) - `.env.*.local` - Mode-specific local overrides (gitignored) **Environment Variable Precedence (Highest to Lowest):** + 1. **Shell Script Overrides** - Platform-specific overrides in build scripts 2. **Environment-Specific .env Files** - `.env.development`, `.env.test`, `.env.production` 3. **Fallback .env File** - General `.env` file (if mode-specific file doesn't exist) 4. **Hardcoded Constants** - Default values in `src/constants/app.ts` **Key Environment Variables:** + ```bash # API Servers (Environment-specific) VITE_DEFAULT_ENDORSER_API_SERVER=https://api.endorser.ch @@ -1604,13 +1691,17 @@ VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZY ``` **Platform-Specific Overrides:** -- **Android Development**: `http://10.0.2.2:3000` (emulator) or custom IP (physical device) -- **iOS Development**: `http://localhost:3000` (simulator) or custom IP (physical device) -#### Build Output Structure +- **Android Development**: `http://10.0.2.2:3000` (emulator) or custom IP +(physical device) +- **iOS Development**: `http://localhost:3000` (simulator) or custom IP (physical +device) + +#### Build Process Output Structure **Web Build:** -``` + +```folders dist/ ├── index.html # Main HTML file ├── assets/ # Bundled JavaScript/CSS @@ -1620,7 +1711,8 @@ dist/ ``` **Electron Build:** -``` + +```folders electron/ ├── app/ # Web assets ├── build/ # Compiled TypeScript @@ -1635,35 +1727,41 @@ electron/ #### Manual vs Automatic Steps **Manual Steps (Developer Responsibility):** + - Database migration testing - Service worker script formatting (optional) - Version updates and changelog - Environment-specific builds **Automatic Steps (Build System):** + - Code linting and formatting - Script combination - Asset optimization - Package creation - Service worker injection -This architecture ensures consistent builds across all platforms while providing flexibility for platform-specific optimizations and manual quality assurance steps. +This architecture ensures consistent builds across all platforms while providing +flexibility for platform-specific optimizations and manual quality assurance steps. --- ## Appendix A: Build Scripts Reference -This appendix provides detailed documentation for all build scripts in the `scripts/` directory. +This appendix provides detailed documentation for all build scripts in the +`scripts/` directory. ### A.1 build-web.sh -**File**: `scripts/build-web.sh` -**Author**: Matthew Raymer +**File**: `scripts/build-web.sh` +**Author**: Matthew Raymer **Description**: Web build script for TimeSafari application -**Purpose**: Handles the complete web build process including cleanup, environment setup, Vite build, and optional Docker containerization. +**Purpose**: Handles the complete web build process including cleanup, +environment setup, Vite build, and optional Docker containerization. **Usage**: + ```bash # Direct script usage ./scripts/build-web.sh # Development build @@ -1687,11 +1785,13 @@ npm run build:web:docker:prod # Production Docker build ``` **Build Modes**: + - **Development**: Starts Vite dev server with hot reload (default) - **Test**: Optimized for testing with minimal minification - **Production**: Optimized for production with full minification **Script Features**: + - **Environment Validation**: Checks for Node.js, npm, npx, package.json - **Environment Setup**: Loads `.env` files based on build mode - **Clean Build**: Removes previous `dist/` directory @@ -1700,6 +1800,7 @@ npm run build:web:docker:prod # Production Docker build - **Local Serving**: Built-in HTTP server for testing builds **Exit Codes**: + - `1` - Web cleanup failed - `2` - Environment setup failed - `3` - Vite build failed @@ -1709,13 +1810,15 @@ npm run build:web:docker:prod # Production Docker build ### A.2 build-electron.sh -**File**: `scripts/build-electron.sh` -**Author**: Matthew Raymer +**File**: `scripts/build-electron.sh` +**Author**: Matthew Raymer **Description**: Clean, modular Electron build script for TimeSafari application -**Purpose**: Handles Electron builds with proper separation of concerns and no command chaining, following DRY principles. +**Purpose**: Handles Electron builds with proper separation of concerns and no +command chaining, following DRY principles. **Usage**: + ```bash # Direct script usage ./scripts/build-electron.sh # Development build (runs app) @@ -1738,22 +1841,26 @@ npm run build:web:docker:prod # Production Docker build ``` **Build Modes**: + - **Development**: Development build (runs app) - **Test**: Test environment build - **Production**: Production environment build - **Clean**: Clean Electron build artifacts only **Platforms**: + - **Windows**: Windows build - **macOS**: macOS build - **Linux**: Linux build **Packages**: + - **AppImage**: Linux AppImage - **Deb**: Debian package - **DMG**: macOS DMG **Exit Codes**: + - `1` - Invalid arguments - `2` - Electron cleanup failed - `3` - Web build failed @@ -1765,21 +1872,23 @@ npm run build:web:docker:prod # Production Docker build ### A.3 build-android.sh -**File**: `scripts/build-android.sh` -**Author**: Matthew Raymer -**Date**: 2025-07-11 +**File**: `scripts/build-android.sh` +**Author**: Matthew Raymer +**Date**: 2025-07-11 **Description**: Android build script for TimeSafari application -**Purpose**: Handles the complete Android build process including cleanup, web build, Capacitor build, Gradle build, and Android Studio launch. +**Purpose**: Handles the complete Android build process including cleanup, web + build, Capacitor build, Gradle build, and Android Studio launch. **Usage**: + ```bash # Direct script usage ./scripts/build-android.sh [options] # Options --dev, --development Build for development environment ---test Build for testing environment +--test Build for testing environment --prod, --production Build for production environment --debug Build debug APK --release Build release APK @@ -1802,15 +1911,18 @@ npm run build:web:docker:prod # Production Docker build ``` **Build Modes**: + - **Development**: Build for development environment - **Test**: Build for testing environment - **Production**: Build for production environment **Build Types**: + - **Debug**: Build debug APK (default) - **Release**: Build release APK **Exit Codes**: + - `1` - Android cleanup failed - `2` - Web build failed - `3` - Capacitor build failed @@ -1823,14 +1935,16 @@ npm run build:web:docker:prod # Production Docker build ### A.4 build-ios.sh -**File**: `scripts/build-ios.sh` -**Author**: Matthew Raymer -**Date**: 2025-07-11 +**File**: `scripts/build-ios.sh` +**Author**: Matthew Raymer +**Date**: 2025-07-11 **Description**: iOS build script for TimeSafari application -**Purpose**: Handles the complete iOS build process including cleanup, web build, Capacitor build, Xcode build, and iOS Simulator launch. +**Purpose**: Handles the complete iOS build process including cleanup, web build, + Capacitor build, Xcode build, and iOS Simulator launch. **Usage**: + ```bash # Direct script usage ./scripts/build-ios.sh [options] @@ -1861,15 +1975,18 @@ npm run build:web:docker:prod # Production Docker build ``` **Build Modes**: + - **Development**: Build for development environment - **Test**: Build for testing environment - **Production**: Build for production environment **Build Types**: + - **Debug**: Build debug app (default) - **Release**: Build release app **Key Features**: + - **Environment Validation**: Checks for Xcode, iOS Simulator, Capacitor - **Resource Checking**: Validates app icons, splash screens, Info.plist - **Clean Build**: Removes Xcode build artifacts and DerivedData @@ -1878,15 +1995,17 @@ npm run build:web:docker:prod # Production Docker build ### A.5 common.sh -**File**: `scripts/common.sh` -**Author**: Matthew Raymer +**File**: `scripts/common.sh` +**Author**: Matthew Raymer **Description**: Common utilities and functions for build scripts -**Purpose**: Provides shared functionality, logging, environment setup, and utility functions used by all build scripts. +**Purpose**: Provides shared functionality, logging, environment setup, and +utility functions used by all build scripts. **Key Functions**: **Logging Functions**: + ```bash log_info "message" # Info level logging log_success "message" # Success level logging @@ -1896,6 +2015,7 @@ log_debug "message" # Debug level logging ``` **Environment Functions**: + ```bash setup_build_env "platform" # Setup build environment for platform load_env_file "filename" # Load environment variables from file @@ -1903,6 +2023,7 @@ print_env_vars "prefix" # Print environment variables with prefix ``` **Utility Functions**: + ```bash check_command "command" # Check if command is available check_file "filename" # Check if file exists @@ -1911,6 +2032,7 @@ clean_build_artifacts "dir" # Clean build artifacts directory ``` **Validation Functions**: + ```bash validate_build_environment # Validate common build environment setup_app_directories # Setup application directories @@ -1919,13 +2041,15 @@ print_header "title" # Print formatted header ### A.6 Cleaning Commands -**File**: `package.json` scripts -**Author**: Matthew Raymer +**File**: `package.json` scripts +**Author**: Matthew Raymer **Description**: Platform-specific and comprehensive cleaning commands -**Purpose**: Provides commands to clean build artifacts for individual platforms or all platforms at once. +**Purpose**: Provides commands to clean build artifacts for individual platforms +or all platforms at once. **Available Commands**: + ```bash # Platform-specific cleaning npm run clean:ios # Clean iOS build artifacts @@ -1944,26 +2068,31 @@ npm run build:electron:clean # Clean Electron build artifacts (via build scrip **Command Details**: **clean:ios**: + - Removes iOS build directories (`ios/App/build`, `ios/App/Pods`, etc.) - Cleans DerivedData and Capacitor artifacts - Safe to run multiple times **clean:android**: + - Uninstalls app from connected devices - Cleans Android build artifacts - Safe to run multiple times **clean:electron**: + - Cleans Electron build artifacts (`electron/build`, `electron/dist`, `electron/app`) - Removes TypeScript compilation artifacts - Safe to run multiple times **clean:all**: + - Executes all platform-specific clean commands in sequence - Stops on first failure (uses `&&` operator) - Most convenient for complete cleanup **Usage Examples**: + ```bash # Clean everything before a fresh build npm run clean:all @@ -1981,17 +2110,20 @@ npm run build:web:dev ## Appendix B: Vite Configuration Files Reference -This appendix provides detailed documentation for all Vite configuration files used in the TimeSafari build system. +This appendix provides detailed documentation for all Vite configuration files used +in the TimeSafari build system. ### B.1 vite.config.common.mts -**File**: `vite.config.common.mts` -**Author**: Matthew Raymer +**File**: `vite.config.common.mts` +**Author**: Matthew Raymer **Description**: Common Vite configuration shared across all platforms -**Purpose**: Provides base configuration that is extended by platform-specific configs with unified environment handling and platform detection. +**Purpose**: Provides base configuration that is extended by platform-specific +configs with unified environment handling and platform detection. **Key Features**: + - **Platform Detection**: Automatically detects and configures for web/capacitor/electron - **Environment Setup**: Loads environment variables and sets platform flags - **Path Aliases**: Configures TypeScript path resolution and module aliases @@ -1999,6 +2131,7 @@ This appendix provides detailed documentation for all Vite configuration files u - **Dependency Management**: Handles platform-specific dependencies **Configuration Structure**: + ```typescript export async function createBuildConfig(platform: string): Promise { const appConfig = await loadAppConfig(); @@ -2066,25 +2199,29 @@ export async function createBuildConfig(platform: string): Promise { ``` **Environment Variables**: + - `VITE_PLATFORM`: Set to platform name (web/capacitor/electron) - `__IS_MOBILE__`: Boolean flag for mobile platforms - `__IS_ELECTRON__`: Boolean flag for Electron platform - `__USE_QR_READER__`: Boolean flag for QR reader availability **Path Aliases**: + - `@`: Points to `src/` directory - `@nostr/tools`: Nostr tools library - `path`, `fs`, `crypto`: Node.js polyfills for browser ### B.2 vite.config.web.mts -**File**: `vite.config.web.mts` -**Author**: Matthew Raymer +**File**: `vite.config.web.mts` +**Author**: Matthew Raymer **Description**: Vite configuration for web platform with PWA support -**Purpose**: Configures Vite for web builds with environment-specific optimizations and PWA features. +**Purpose**: Configures Vite for web builds with environment-specific +optimizations and PWA features. **Key Features**: + - **Environment-Specific Configuration**: Different settings for dev/test/prod - **PWA Integration**: Progressive Web App support with service worker - **Build Optimization**: Manual chunk splitting for better caching @@ -2094,6 +2231,7 @@ export async function createBuildConfig(platform: string): Promise { **Environment Configurations**: **Development Mode**: + ```typescript { build: { @@ -2110,6 +2248,7 @@ export async function createBuildConfig(platform: string): Promise { ``` **Test Mode**: + ```typescript { build: { @@ -2126,6 +2265,7 @@ export async function createBuildConfig(platform: string): Promise { ``` **Production Mode**: + ```typescript { build: { @@ -2151,6 +2291,7 @@ export async function createBuildConfig(platform: string): Promise { ``` **PWA Configuration**: + ```typescript VitePWA({ registerType: 'autoUpdate', @@ -2169,13 +2310,15 @@ VitePWA({ ### B.3 vite.config.electron.mts -**File**: `vite.config.electron.mts` -**Author**: Matthew Raymer +**File**: `vite.config.electron.mts` +**Author**: Matthew Raymer **Description**: Vite configuration for Electron desktop platform -**Purpose**: Configures Vite for Electron builds with desktop-specific optimizations and native module support. +**Purpose**: Configures Vite for Electron builds with desktop-specific optimizations + and native module support. **Key Features**: + - **Electron-Specific Entry Point**: Uses `main.electron.ts` instead of `main.web.ts` - **Native Module Support**: Handles Electron-specific dependencies - **Desktop Optimizations**: Larger chunk sizes and desktop-specific settings @@ -2183,10 +2326,11 @@ VitePWA({ - **External Dependencies**: Properly handles Electron and native modules **Configuration Structure**: + ```typescript export default defineConfig(async () => { const baseConfig = await createBuildConfig("electron"); - + return { ...baseConfig, plugins: [ @@ -2220,24 +2364,28 @@ export default defineConfig(async () => { ``` **Plugins**: + - **electron-entry-point**: Replaces main entry point for Electron - **electron-config**: Handles Electron-specific configurations - **suppress-source-maps**: Suppresses source map loading errors **External Dependencies**: + - `electron`: Electron runtime - `@capacitor-community/electron`: Capacitor Electron plugin - `better-sqlite3-multiple-ciphers`: Native SQLite module ### B.4 vite.config.capacitor.mts -**File**: `vite.config.capacitor.mts` -**Author**: Matthew Raymer +**File**: `vite.config.capacitor.mts` +**Author**: Matthew Raymer **Description**: Vite configuration for Capacitor mobile platform -**Purpose**: Provides minimal configuration for Capacitor builds, inheriting from common config. +**Purpose**: Provides minimal configuration for Capacitor builds, inheriting from +common config. **Configuration**: + ```typescript import { defineConfig } from "vite"; import { createBuildConfig } from "./vite.config.common.mts"; @@ -2246,6 +2394,7 @@ export default defineConfig(async () => createBuildConfig('capacitor')); ``` **Key Features**: + - **Minimal Configuration**: Inherits all settings from common config - **Mobile Platform**: Automatically configures for mobile-specific settings - **PWA Disabled**: Progressive Web App features disabled for native apps @@ -2253,8 +2402,8 @@ export default defineConfig(async () => createBuildConfig('capacitor')); ### B.5 vite.config.utils.mts -**File**: `vite.config.utils.mts` -**Author**: Matthew Raymer +**File**: `vite.config.utils.mts` +**Author**: Matthew Raymer **Description**: Utility functions for Vite configuration **Purpose**: Provides shared configuration loading and PWA manifest generation. @@ -2266,6 +2415,7 @@ export default defineConfig(async () => createBuildConfig('capacitor')); **loadAppConfig()**: Loads complete application configuration including PWA settings **PWA Configuration**: + ```typescript interface PWAConfig { registerType: string; @@ -2284,11 +2434,13 @@ interface PWAConfig { ``` **Manifest Icons**: + - Android Chrome 192x192 PNG - Android Chrome 512x512 PNG - Maskable icons for adaptive UI **Share Target Configuration**: + ```typescript share_target: { action: "/share-target", @@ -2301,6 +2453,7 @@ share_target: { ``` **Alias Configuration**: + - `@`: Source directory alias - `buffer`: Buffer polyfill - `dexie-export-import`: Database import/export utilities @@ -2335,23 +2488,27 @@ source "$(dirname "$0")/common.sh" ### C.3 Build Process Flow **Web Build**: -``` + +```text build-web.sh → vite.config.web.mts → dist/ ``` **Electron Build**: -``` + +```text build-electron.sh → vite.config.electron.mts → electron/app/ ``` **Mobile Build**: -``` + +```text build-android.sh/build-ios.sh → vite.config.capacitor.mts → android/ios/ ``` ### C.4 Error Handling All scripts use consistent error handling: + - Exit codes for different failure types - Verbose logging with `--verbose` flag - Safe command execution with `safe_execute()` @@ -2360,20 +2517,25 @@ All scripts use consistent error handling: ### C.5 Platform-Specific Considerations **Web Platform**: + - PWA features enabled - Service worker injection - Browser-specific optimizations **Electron Platform**: + - Native module support - Desktop-specific entry points - Source map suppression **Mobile Platform**: + - Capacitor integration - Native asset generation - Platform-specific builds --- -**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. +**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/CHANGELOG.md b/CHANGELOG.md index 19209fb6..641ff920 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,69 +6,88 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [1.0.7] - 2025.08.18 + ### Fixed -- Deep link for onboard-meeting-members +- Deep link for onboard-meeting-members ## [1.0.6] - 2025.08.09 + ### Fixed -- Deep link errors where none would validate +- Deep link errors where none would validate ## [1.0.5] - 2025.07.24 + ### Fixed -- Export & import of contacts corrupted contact methods +- Export & import of contacts corrupted contact methods ## [1.0.4] - 2025.07.20 - 002f2407208d56cc59c0aa7c880535ae4cbace8b + ### Fixed -- Deep link for invite-one-accept +- Deep link for invite-one-accept ## [1.0.3] - 2025.07.12 - a9a8ba217cd6015321911e98e6843e988dc2c4ae + ### Changed + - Photo is pinned to profile mode + ### Fixed + - Deep link URLs (and other prod settings) - Error in BVC begin view - ## [1.0.2] - 2025.06.20 - 276e0a741bc327de3380c4e508cccb7fee58c06d + ### Added -- Version on feed title +- Version on feed title ## [1.0.1] - 2025.06.20 + ### Added -- Allow a user to block someone else's content from view +- Allow a user to block someone else's content from view ## [1.0.0] - 2025.06.20 - 5aa693de6337e5dbb278bfddc6bd39094bc14f73 + ### Added -- Web-oriented migration from IndexedDB to SQLite +- Web-oriented migration from IndexedDB to SQLite ## [0.5.8] + ### Added + - /deep-link/ path for URLs that are shared with people + ### Changed + - External links now go to /deep-link/... - Feed visuals now have arrow imagery from giver to receiver - ## [0.4.7] + ### Fixed + - Cameras everywhere + ### Changed -- IndexedDB -> SQLite +- IndexedDB -> SQLite ## [0.4.5] - 2025.02.23 + ### Added + - Total amounts of gives on project page + ### Changed in DB or environment -- Requires Endorser.ch version 4.2.6+ +- Requires Endorser.ch version 4.2.6+ ## [0.4.4] - 2025.02.17 diff --git a/TASK_storage.md b/TASK_storage.md index a33cbb87..52b52b76 100644 --- a/TASK_storage.md +++ b/TASK_storage.md @@ -1,7 +1,6 @@ # What to do about storage for native apps? - ## Problem We can't trust iOS IndexedDB to persist. I want to start delivering an app to people now, in preparation for presentations mid-June: Rotary on June 12 and Porcfest on June 17. @@ -14,7 +13,6 @@ We can't trust iOS IndexedDB to persist. I want to start delivering an app to pe Also, with sensitive data, the accounts info should be encrypted. - # Options * There is a community [SQLite plugin for Capacitor](https://github.com/capacitor-community/sqlite) with encryption by [SQLCipher](https://github.com/sqlcipher/sqlcipher). @@ -29,16 +27,12 @@ Also, with sensitive data, the accounts info should be encrypted. * Not an option yet: Dexie may support SQLite in [a future version](https://dexie.org/roadmap/dexie5.0). - - # Current Plan * Implement SQLite for Capacitor & web, with encryption. That will allow us to test quickly and keep the same interface for native & web, but we don't deal with migrations for current web users. * After that is delivered, write a migration for current web users from IndexedDB to SQLite. - - # Current method calls ... which is not 100% complete because the AI that generated thus claimed no usage of 'temp' DB. @@ -80,5 +74,3 @@ Logs operations: db.logs.get(todayKey) - Gets logs for a specific day db.logs.update(todayKey, { message: fullMessage }) - Updates logs db.logs.clear() - Clears all logs - - diff --git a/doc/DEEP_LINKS.md b/doc/DEEP_LINKS.md index a6bf9f6b..8638074b 100644 --- a/doc/DEEP_LINKS.md +++ b/doc/DEEP_LINKS.md @@ -47,6 +47,7 @@ type ClaimParams = z.infer; ### Type Safety Layers 1. **Schema Definition** + ```typescript // src/interfaces/deepLinks.ts export const deepLinkSchemas = { @@ -59,6 +60,7 @@ type ClaimParams = z.infer; ``` 2. **Type Generation** + ```typescript // Types are automatically generated from schemas export type DeepLinkParams = { @@ -67,6 +69,7 @@ type ClaimParams = z.infer; ``` 3. **Runtime Validation** + ```typescript // In DeepLinkHandler const result = deepLinkSchemas.claim.safeParse(params); diff --git a/doc/README.md b/doc/README.md index 45e98fc4..3e876ca0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -6,7 +6,7 @@ This uses Pandoc and BasicTex (LaTeX) Installed through Homebrew. ### Set Up -```bash +```bash brew install pandoc brew install basictex @@ -54,7 +54,7 @@ sudo tlmgr install sourceserifpro The following guide was adapted to this project except that we install with Brew and have a few more packages. -Guide: https://daniel.feldroy.com/posts/setting-up-latex-on-mac-os-x +Guide: ### Usage @@ -71,6 +71,7 @@ open usage-guide.pdf ``` Or use this one-liner + ```bash pandoc usage-guide.md -o usage-guide.pdf && open usage-guide.pdf ``` diff --git a/doc/architecture-decisions.md b/doc/architecture-decisions.md index 40fa3d3f..11861b8f 100644 --- a/doc/architecture-decisions.md +++ b/doc/architecture-decisions.md @@ -122,4 +122,4 @@ export default class HomeView extends Vue { --- -*This decision was made based on the current codebase architecture and team expertise. The mixin approach provides the best balance of performance, developer experience, and architectural consistency for the TimeSafari application.* \ No newline at end of file +*This decision was made based on the current codebase architecture and team expertise. The mixin approach provides the best balance of performance, developer experience, and architectural consistency for the TimeSafari application.* diff --git a/doc/asset-migration-plan.md b/doc/asset-migration-plan.md index 3a05353c..86c0954e 100644 --- a/doc/asset-migration-plan.md +++ b/doc/asset-migration-plan.md @@ -103,6 +103,7 @@ scripts/ ### Configuration Schema The schema enforces: + - Source files must be in `resources/` directory - Required fields for icon and splash sections - Android adaptive icon support (foreground/background/monochrome) diff --git a/doc/build-modernization-context.md b/doc/build-modernization-context.md index 133c2ad6..4f2ae09e 100644 --- a/doc/build-modernization-context.md +++ b/doc/build-modernization-context.md @@ -3,11 +3,13 @@ **Author:** Matthew Raymer ## Motivation + - Eliminate manual hacks and post-build scripts for Electron builds - Ensure maintainability, reproducibility, and security of build outputs - Unify build, test, and deployment scripts for developer experience and CI/CD ## Key Technical Decisions + - **Vite is the single source of truth for build output** - All Electron build output (main process, preload, renderer HTML/CSS/JS) is managed by `vite.config.electron.mts` - **CSS injection for Electron is handled by a Vite plugin** @@ -21,6 +23,7 @@ - Renderer assets: `dist-electron/www/` (HTML, CSS, JS) ## Security & Maintenance Checklist + - [x] All scripts and configs are committed and documented - [x] No manual file hacks remain - [x] All build output is deterministic and reproducible @@ -28,24 +31,29 @@ - [x] Documentation (`BUILDING.md`) is up to date ## How to Build Electron + 1. Run: + ```bash ./scripts/build-electron.sh ``` + 2. Output will be in `dist-electron/`: - `main.js`, `preload.js` in root - `www/` contains all renderer assets 3. No manual post-processing is required ## Customization + - **Vite config:** All build output and asset handling is controlled in `vite.config.electron.mts` - **CSS/HTML injection:** Use Vite plugins (see `electron-css-injection` in the config) for further customization - **Build scripts:** All orchestration is in `scripts/` and documented in `BUILDING.md` ## For Future Developers + - Always use Vite plugins/config for build output changes - Never manually edit built files or inject assets post-build - Keep documentation and scripts in sync with the build process --- -This file documents the context and rationale for the build modernization and should be included in the repository for onboarding and future reference. \ No newline at end of file +This file documents the context and rationale for the build modernization and should be included in the repository for onboarding and future reference. diff --git a/doc/circular-dependency-analysis.md b/doc/circular-dependency-analysis.md index 0ae322dc..a6530e62 100644 --- a/doc/circular-dependency-analysis.md +++ b/doc/circular-dependency-analysis.md @@ -13,27 +13,31 @@ The codebase currently has **no active circular dependencies** that are causing ### 🔍 **Resolved Dependency Patterns** #### 1. **Logger → PlatformServiceFactory → Logger** (RESOLVED) + - **Status**: ✅ **RESOLVED** - **Previous Issue**: Logger imported `logToDb` from databaseUtil, which imported logger - **Solution**: Logger now uses direct database access via PlatformServiceFactory - **Implementation**: Self-contained `logToDatabase()` function in logger.ts #### 2. **PlatformServiceMixin → databaseUtil → logger → PlatformServiceMixin** (RESOLVED) + - **Status**: ✅ **RESOLVED** - **Previous Issue**: PlatformServiceMixin imported `memoryLogs` from databaseUtil - **Solution**: Created self-contained `_memoryLogs` array in PlatformServiceMixin - **Implementation**: Self-contained memory logs implementation #### 3. **databaseUtil → logger → PlatformServiceFactory → databaseUtil** (RESOLVED) + - **Status**: ✅ **RESOLVED** - **Previous Issue**: databaseUtil imported logger, which could create loops - **Solution**: Logger is now self-contained and doesn't import from databaseUtil #### 4. **Utility Files → databaseUtil → PlatformServiceMixin** (RESOLVED) + - **Status**: ✅ **RESOLVED** - **Previous Issue**: `src/libs/util.ts` and `src/services/deepLinks.ts` imported from databaseUtil - **Solution**: Replaced with self-contained implementations and PlatformServiceFactory usage -- **Implementation**: +- **Implementation**: - Self-contained `parseJsonField()` and `mapQueryResultToValues()` functions - Direct PlatformServiceFactory usage for database operations - Console logging instead of databaseUtil logging functions @@ -43,18 +47,21 @@ The codebase currently has **no active circular dependencies** that are causing ### ✅ **All Critical Dependencies Resolved** #### PlatformServiceMixin Independence + - **Status**: ✅ **COMPLETE** - **Achievement**: PlatformServiceMixin has no external dependencies on databaseUtil - **Implementation**: Self-contained memory logs and utility functions - **Impact**: Enables complete migration of databaseUtil functions to PlatformServiceMixin #### Logger Independence + - **Status**: ✅ **COMPLETE** - **Achievement**: Logger is completely self-contained - **Implementation**: Direct database access via PlatformServiceFactory - **Impact**: Eliminates all circular dependency risks #### Utility Files Independence + - **Status**: ✅ **COMPLETE** - **Achievement**: All utility files no longer depend on databaseUtil - **Implementation**: Self-contained functions and direct platform service access @@ -63,6 +70,7 @@ The codebase currently has **no active circular dependencies** that are causing ### 🎯 **Migration Readiness Status** #### Files Ready for Migration (52 files) + 1. **Components** (15 files): - `PhotoDialog.vue` - `FeedFilters.vue` @@ -98,6 +106,7 @@ The codebase currently has **no active circular dependencies** that are causing ### 🟢 **Healthy Dependencies** #### Logger Usage (80+ files) + - **Status**: ✅ **HEALTHY** - **Pattern**: All files import logger from `@/utils/logger` - **Impact**: No circular dependencies, logger is self-contained @@ -106,21 +115,25 @@ The codebase currently has **no active circular dependencies** that are causing ## Resolution Strategy - COMPLETED ### ✅ **Phase 1: Complete PlatformServiceMixin Independence (COMPLETE)** + 1. **Removed memoryLogs import** from PlatformServiceMixin ✅ 2. **Created self-contained memoryLogs** implementation ✅ 3. **Added missing utility methods** to PlatformServiceMixin ✅ ### ✅ **Phase 2: Utility Files Migration (COMPLETE)** + 1. **Migrated deepLinks.ts** - Replaced databaseUtil logging with console logging ✅ 2. **Migrated util.ts** - Replaced databaseUtil functions with self-contained implementations ✅ 3. **Updated all PlatformServiceFactory calls** to use async pattern ✅ ### 🎯 **Phase 3: File-by-File Migration (READY TO START)** + 1. **High-usage files first** (views, core components) 2. **Replace databaseUtil imports** with PlatformServiceMixin 3. **Update function calls** to use mixin methods ### 🎯 **Phase 4: Cleanup (FUTURE)** + 1. **Remove unused databaseUtil functions** 2. **Update TypeScript interfaces** 3. **Remove databaseUtil imports** from all files @@ -128,6 +141,7 @@ The codebase currently has **no active circular dependencies** that are causing ## Current Status Summary ### ✅ **Resolved Issues** + 1. **Logger circular dependency** - Fixed with self-contained implementation 2. **PlatformServiceMixin circular dependency** - Fixed with self-contained memoryLogs 3. **Utility files circular dependency** - Fixed with self-contained implementations @@ -135,6 +149,7 @@ The codebase currently has **no active circular dependencies** that are causing 5. **Runtime stability** - No circular dependency crashes ### 🎯 **Ready for Next Phase** + 1. **52 files** ready for databaseUtil migration 2. **PlatformServiceMixin** fully independent and functional 3. **Clear migration path** - Well-defined targets and strategy @@ -142,6 +157,7 @@ The codebase currently has **no active circular dependencies** that are causing ## Benefits of Current State ### ✅ **Achieved** + 1. **No runtime circular dependencies** - Application runs without crashes 2. **Self-contained logger** - No more logger/databaseUtil loops 3. **PlatformServiceMixin ready** - All methods implemented and independent @@ -149,6 +165,7 @@ The codebase currently has **no active circular dependencies** that are causing 5. **Clear migration path** - Well-defined targets and strategy ### 🎯 **Expected After Migration** + 1. **Complete databaseUtil migration** - Single source of truth 2. **Eliminated circular dependencies** - Clean architecture 3. **Improved performance** - Caching and optimization @@ -160,4 +177,4 @@ The codebase currently has **no active circular dependencies** that are causing **Created**: 2025-07-05 **Status**: ✅ **COMPLETE - All Circular Dependencies Resolved** **Last Updated**: 2025-01-06 -**Note**: PlatformServiceMixin circular dependency completely resolved. Ready for Phase 2: File-by-File Migration \ No newline at end of file +**Note**: PlatformServiceMixin circular dependency completely resolved. Ready for Phase 2: File-by-File Migration diff --git a/doc/component-communication-guide.md b/doc/component-communication-guide.md index 1fad5968..797e5740 100644 --- a/doc/component-communication-guide.md +++ b/doc/component-communication-guide.md @@ -93,6 +93,7 @@ export default class FormComponent extends Vue { When generating component templates, follow these patterns: #### Function Props Template + ```vue