docs: comprehensive documentation updates and modernization
- Update BUILDING.md with current build system information
- Modernize various README files across the project
- Update CHANGELOG.md with recent changes
- Improve documentation consistency and formatting
- Update platform-specific documentation (iOS, Electron, Docker)
- Enhance test documentation and build guides
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.
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.
Also, with sensitive data, the accounts info should be encrypted.
# Options
# Options
* There is a community [SQLite plugin for Capacitor](https://github.com/capacitor-community/sqlite) with encryption by [SQLCipher](https://github.com/sqlcipher/sqlcipher).
* 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).
* Not an option yet: Dexie may support SQLite in [a future version](https://dexie.org/roadmap/dexie5.0).
# Current Plan
# 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.
* 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.
* After that is delivered, write a migration for current web users from IndexedDB to SQLite.
# Current method calls
# Current method calls
... which is not 100% complete because the AI that generated thus claimed no usage of 'temp' DB.
... 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.get(todayKey) - Gets logs for a specific day
- Changed `logger.warn` to `logger.debug` for routine SQL operations
- Changed `logger.warn` to `logger.debug` for routine SQL operations
- Reduced migration logging verbosity
- Reduced migration logging verbosity
- Made database integrity checks use debug-level logging
- Made database integrity checks use debug-level logging
- Kept error and completion messages at appropriate log levels
- Kept error and completion messages at appropriate log levels
### 2. Enhanced Logger Configuration
### 2. Enhanced Logger Configuration
**Problem:** No platform-specific logging controls, causing noise in Electron.
**Problem:** No platform-specific logging controls, causing noise in Electron.
**Solution:** Updated `src/utils/logger.ts`:
**Solution:** Updated `src/utils/logger.ts`:
- Added platform detection for Electron vs Web
- Added platform detection for Electron vs Web
- Suppressed debug and verbose logs for Electron
- Suppressed debug and verbose logs for Electron
- Filtered out routine database operations from database logging
- Filtered out routine database operations from database logging
@ -26,28 +30,35 @@ This document summarizes the comprehensive changes made to reduce excessive cons
- Added intelligent filtering for CapacitorPlatformService messages
- Added intelligent filtering for CapacitorPlatformService messages
### 3. API Configuration Issues (Major Fix)
### 3. API Configuration Issues (Major Fix)
**Problem:** Electron was trying to use local development endpoints (localhost:3000) from saved user settings, which don't exist in desktop environment, causing:
**Problem:** Electron was trying to use local development endpoints (localhost:3000) from saved user settings, which don't exist in desktop environment, causing:
- 400 status errors from missing local development servers
- 400 status errors from missing local development servers
- Updated `src/constants/app.ts` to provide Electron-specific API endpoints
- Updated `src/constants/app.ts` to provide Electron-specific API endpoints
- **Critical Fix:** Modified `src/db/databaseUtil.ts` in `retrieveSettingsForActiveAccount()` to force Electron to use production API endpoints regardless of saved user settings
- **Critical Fix:** Modified `src/db/databaseUtil.ts` in `retrieveSettingsForActiveAccount()` to force Electron to use production API endpoints regardless of saved user settings
- This ensures Electron never uses localhost development servers that users might have saved
- This ensures Electron never uses localhost development servers that users might have saved
### 4. SharedArrayBuffer Logging Noise
### 4. SharedArrayBuffer Logging Noise
**Problem:** Web-specific SharedArrayBuffer detection was running in Electron, creating unnecessary debug output.
**Problem:** Web-specific SharedArrayBuffer detection was running in Electron, creating unnecessary debug output.
**Solution:** Modified `src/main.web.ts`:
**Solution:** Modified `src/main.web.ts`:
- Made SharedArrayBuffer logging conditional on web platform only
- Made SharedArrayBuffer logging conditional on web platform only
- Converted console.log statements to logger.debug
- Converted console.log statements to logger.debug
- Only show in development mode for web platform
- Only show in development mode for web platform
- Reduced platform detection noise
- Reduced platform detection noise
### 5. Missing Source Maps Warnings
### 5. Missing Source Maps Warnings
**Problem:** Electron DevTools was complaining about missing source maps for external dependencies.
**Problem:** Electron DevTools was complaining about missing source maps for external dependencies.
**Solution:** Updated `vite.config.electron.mts`:
**Solution:** Updated `vite.config.electron.mts`:
- Disabled source maps for Electron builds (`sourcemap: false`)
- Disabled source maps for Electron builds (`sourcemap: false`)
- Added build configuration to suppress external dependency warnings
- Added build configuration to suppress external dependency warnings
- Prevents DevTools from looking for non-existent source map files
- Prevents DevTools from looking for non-existent source map files
@ -87,14 +98,16 @@ This document summarizes the comprehensive changes made to reduce excessive cons
## Impact
## Impact
### Before Cleanup:
### Before Cleanup
- 500+ lines of console output per minute
- 500+ lines of console output per minute
- Detailed SQL parameter logging for every operation
- Detailed SQL parameter logging for every operation
- API connection errors every few seconds (400 status, JSON parsing errors)
- API connection errors every few seconds (400 status, JSON parsing errors)
- SharedArrayBuffer warnings on every startup
- SharedArrayBuffer warnings on every startup
- DevTools source map warnings
- DevTools source map warnings
### After Cleanup:
### After Cleanup
- **~95% reduction** in console output
- **~95% reduction** in console output
- Only errors and important status messages visible
- Only errors and important status messages visible
- **No API connection errors** - Electron uses proper production endpoints
- **No API connection errors** - Electron uses proper production endpoints
@ -106,6 +119,7 @@ This document summarizes the comprehensive changes made to reduce excessive cons
## Technical Details
## Technical Details
### API Configuration Fix
### API Configuration Fix
The most critical fix was in `src/db/databaseUtil.ts` where we added:
The most critical fix was in `src/db/databaseUtil.ts` where we added:
```typescript
```typescript
@ -122,6 +136,7 @@ if (process.env.VITE_PLATFORM === "electron") {
This ensures that even if users have localhost development endpoints saved in their settings, Electron will override them with production endpoints.
This ensures that even if users have localhost development endpoints saved in their settings, Electron will override them with production endpoints.
### Logger Enhancement
### Logger Enhancement
Enhanced the logger with platform-specific behavior:
Enhanced the logger with platform-specific behavior:
```typescript
```typescript
@ -135,6 +150,7 @@ if (!isElectron || !message.includes("[CapacitorPlatformService]")) {
## Testing
## Testing
The changes were tested with:
The changes were tested with:
- `npm run lint-fix` - 0 errors, warnings only (pre-existing)
- `npm run lint-fix` - 0 errors, warnings only (pre-existing)
- Must be served over **HTTPS** (except `localhost` for dev).
- Must be served over **HTTPS** (except `localhost` for dev).
- These headers enforce **cross-origin isolation**.
- These headers enforce **cross-origin isolation**.
### Role of CORS
### Role of CORS
- CORS **alone is not sufficient**.
- CORS **alone is not sufficient**.
- However, embedded resources (like scripts and iframes) must still include proper CORS headers if they are to be loaded in a cross-origin isolated context.
- However, embedded resources (like scripts and iframes) must still include proper CORS headers if they are to be loaded in a cross-origin isolated context.
## 3. Spectre Vulnerability
## 3. Spectre Vulnerability
### What is Spectre?
### What is Spectre?
- A class of **side-channel attacks** exploiting **speculative execution** in CPUs.
- A class of **side-channel attacks** exploiting **speculative execution** in CPUs.
- Allows an attacker to read arbitrary memory from the same address space.
- Allows an attacker to read arbitrary memory from the same address space.
### Affected Architectures
### Affected Architectures
- Intel, AMD, ARM — essentially **all modern processors**.
- Intel, AMD, ARM — essentially **all modern processors**.
### Why It's Still a Concern
### Why It's Still a Concern
- It's a **hardware flaw**, not just a software bug.
- It's a **hardware flaw**, not just a software bug.
- Can't be fully fixed in software without performance penalties.
- Can't be fully fixed in software without performance penalties.
- New Spectre **variants** (e.g., v2, RSB, BranchScope) continue to emerge.
- New Spectre **variants** (e.g., v2, RSB, BranchScope) continue to emerge.
The default templates are located in the `Templates` root directory and currently include the following templates:
The default templates are located in the `Templates` root directory and currently include the following templates:
- `Templates/AppTemplate.xcprivacy`
- `Templates/AppTemplate.xcprivacy`
- `Templates/FrameworkTemplate.xcprivacy`
- `Templates/FrameworkTemplate.xcprivacy`
These templates will be modified based on the API usage analysis results, especially the `NSPrivacyAccessedAPIType` entries, to generate new privacy manifests for fixes, ensuring compliance with App Store requirements.
These templates will be modified based on the API usage analysis results, especially the `NSPrivacyAccessedAPIType` entries, to generate new privacy manifests for fixes, ensuring compliance with App Store requirements.
**If adjustments to the privacy manifest template are needed, such as in the following scenarios, avoid directly modifying the default templates. Instead, use a custom template. If a custom template with the same name exists, it will take precedence over the default template for fixes.**
**If adjustments to the privacy manifest template are needed, such as in the following scenarios, avoid directly modifying the default templates. Instead, use a custom template. If a custom template with the same name exists, it will take precedence over the default template for fixes.**
- Generating a non-compliant privacy manifest due to inaccurate API usage analysis.
- Generating a non-compliant privacy manifest due to inaccurate API usage analysis.
- Modifying the reason declared in the template.
- Modifying the reason declared in the template.
- Adding declarations for collected data.
- Adding declarations for collected data.
@ -198,6 +203,7 @@ The privacy access API categories and their associated declared reasons in `Fram
### Custom Templates
### Custom Templates
To create custom templates, place them in the `Templates/UserTemplates` directory with the following structure:
To create custom templates, place them in the `Templates/UserTemplates` directory with the following structure:
@ -205,6 +211,7 @@ To create custom templates, place them in the `Templates/UserTemplates` director
Among these templates, only `FrameworkTemplate.xcprivacy` will be modified based on the API usage analysis results to adjust the `NSPrivacyAccessedAPIType` entries, thereby generating a new privacy manifest for framework fixes. The other templates will remain unchanged and will be directly used for fixes.
Among these templates, only `FrameworkTemplate.xcprivacy` will be modified based on the API usage analysis results to adjust the `NSPrivacyAccessedAPIType` entries, thereby generating a new privacy manifest for framework fixes. The other templates will remain unchanged and will be directly used for fixes.
**Important Notes:**
**Important Notes:**
- The template for a specific framework must follow the naming convention `FrameworkName.xcprivacy`, where `FrameworkName` should match the name of the framework. For example, the template for `Flutter.framework` should be named `Flutter.xcprivacy`.
- The template for a specific framework must follow the naming convention `FrameworkName.xcprivacy`, where `FrameworkName` should match the name of the framework. For example, the template for `Flutter.framework` should be named `Flutter.xcprivacy`.
- For macOS frameworks, the naming convention should be `FrameworkName.Version.xcprivacy`, where the version name is added to distinguish different versions. For a single version macOS framework, the `Version` is typically `A`.
- For macOS frameworks, the naming convention should be `FrameworkName.Version.xcprivacy`, where the version name is added to distinguish different versions. For a single version macOS framework, the `Version` is typically `A`.
- The name of an SDK may not exactly match the name of the framework. To determine the correct framework name, check the `Frameworks` directory in the application bundle after building the project.
- The name of an SDK may not exactly match the name of the framework. To determine the correct framework name, check the `Frameworks` directory in the application bundle after building the project.
@ -5,15 +5,18 @@ This directory contains custom Git hooks for the TimeSafari project.
## Debug Code Checker Hook
## Debug Code Checker Hook
### Overview
### Overview
The `pre-commit` hook automatically checks for debug code when committing to protected branches (master, main, production, release). This prevents debug statements from accidentally reaching production code.
The `pre-commit` hook automatically checks for debug code when committing to protected branches (master, main, production, release). This prevents debug statements from accidentally reaching production code.
### How It Works
### How It Works
1. **Branch Detection**: Only runs on protected branches (configurable)
1. **Branch Detection**: Only runs on protected branches (configurable)
2. **File Filtering**: Automatically skips test files, scripts, and documentation
2. **File Filtering**: Automatically skips test files, scripts, and documentation
3. **Pattern Matching**: Detects common debug patterns using regex
3. **Pattern Matching**: Detects common debug patterns using regex
@ -5,6 +5,7 @@ Start with [README.md](./README.md). This file has more details.
## Test User Setup
## Test User Setup
### Register New User on Test Server
### Register New User on Test Server
On the test server, User #0 has rights to register others. Import User #0 with this seed phrase:
On the test server, User #0 has rights to register others. Import User #0 with this seed phrase:
```bash
```bash
@ -18,6 +19,7 @@ This corresponds to: `did:ethr:0x0000694B58C2cC69658993A90D3840C560f2F51F`
## Manual Testing Steps
## Manual Testing Steps
### Identity Management
### Identity Management
1. Create multiple identifiers:
1. Create multiple identifiers:
- Go to "Your Identity" screen
- Go to "Your Identity" screen
- Click "Advanced"
- Click "Advanced"
@ -96,10 +98,10 @@ npx playwright test -c playwright.config-local.ts test-playwright/60-new-activit
```
```
This command allows you to:
This command allows you to:
- **Run a specific test file**: `test-playwright/60-new-activity.spec.ts`
- **Run a specific test file**: `test-playwright/60-new-activity.spec.ts`
- **Filter to a specific test**: `--grep "New offers for another user"` runs only tests with that name
- **Filter to a specific test**: `--grep "New offers for another user"` runs only tests with that name
- **See the browser**: `--headed` opens the browser window so you can watch the test execute
- **See the browser**: `--headed` opens the browser window so you can watch the test execute
- **Use local config**: `-c playwright.config-local.ts` uses the local configuration file
- **Use local config**: `-c playwright.config-local.ts` uses the local configuration file
This is useful when you want to observe the testing process visually rather than running tests in headless mode. It's particularly helpful for debugging test failures or understanding how the application behaves during automated testing.
This is useful when you want to observe the testing process visually rather than running tests in headless mode. It's particularly helpful for debugging test failures or understanding how the application behaves during automated testing.
Matthew Raymer
1 day ago