diff --git a/README.md b/README.md index de9c63ca..4e6867c9 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,85 @@ npm run dev See [BUILDING.md](BUILDING.md) for more details. +## Development Database Clearing + +TimeSafari provides a simple script-based approach to clear the database for development purposes. + +### Quick Usage +```bash +# Run the database clearing script +./scripts/clear-database.sh + +# Then restart your development server +npm run build:electron:dev # For Electron +npm run build:web:dev # For Web +``` + +### What It Does + +#### **Electron (Desktop App)** +- Automatically finds and clears the SQLite database files +- Works on Linux, macOS, and Windows +- Clears all data and forces fresh migrations on next startup + +#### **Web Browser** +- Provides instructions for using custom browser data directories +- Shows manual clearing via browser DevTools +- Ensures reliable database clearing without browser complications + +### Safety Features +- ✅ **Interactive Script**: Guides you through the process +- ✅ **Platform Detection**: Automatically detects your OS +- ✅ **Clear Instructions**: Step-by-step guidance for each platform +- ✅ **Safe Paths**: Only clears TimeSafari-specific data + +### Manual Commands (if needed) + +#### **Electron Database Location** +```bash +# Linux +rm -rf ~/.config/TimeSafari/* + +# macOS +rm -rf ~/Library/Application\ Support/TimeSafari/* + +# Windows +rmdir /s /q %APPDATA%\TimeSafari +``` + +#### **Web Browser (Custom Data Directory)** +```bash +# Create isolated browser profile +mkdir ~/timesafari-dev-data + +# Start browser with custom profile +google-chrome --user-data-dir=~/timesafari-dev-data + +# Clear when needed +rm -rf ~/timesafari-dev-data +``` + +See the script for complete platform-specific instructions. + +## Electron Build Scripts + +### **Development vs Package Builds** + +- **Development Scripts**: Run the app directly after building + ```bash + npm run build:electron:dev # Runs app immediately + npm run build:electron:test # Runs app immediately + ``` + +- **Package Scripts**: Create executable files for distribution + ```bash + npm run build:electron:appimage # Creates AppImage executable + npm run build:electron:deb # Creates DEB package + npm run build:electron:dmg # Creates DMG package + ``` + +See [Electron Build Scripts Guide](docs/electron-build-scripts.md) for complete details. + ## Tests See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions. @@ -118,63 +197,3 @@ Gifts make the world go 'round! * Time Safari logo assisted by [DALL-E in ChatGPT](https://chat.openai.com/g/g-2fkFE8rbu-dall-e) * [DiceBear](https://www.dicebear.com/licenses/) and [Avataaars](https://www.dicebear.com/styles/avataaars/#details) for human-looking identicons * Some gratitude prompts thanks to [Develop Good Habits](https://www.developgoodhabits.com/gratitude-journal-prompts/) - -## Development Database Clearing - -TimeSafari provides a simple script-based approach to clear the database for development purposes. - -### Quick Usage -```bash -# Run the database clearing script -./scripts/clear-database.sh - -# Then restart your development server -npm run build:electron:dev # For Electron -npm run build:web:dev # For Web -``` - -### What It Does - -#### **Electron (Desktop App)** -- Automatically finds and clears the SQLite database files -- Works on Linux, macOS, and Windows -- Clears all data and forces fresh migrations on next startup - -#### **Web Browser** -- Provides instructions for using custom browser data directories -- Shows manual clearing via browser DevTools -- Ensures reliable database clearing without browser complications - -### Safety Features -- ✅ **Interactive Script**: Guides you through the process -- ✅ **Platform Detection**: Automatically detects your OS -- ✅ **Clear Instructions**: Step-by-step guidance for each platform -- ✅ **Safe Paths**: Only clears TimeSafari-specific data - -### Manual Commands (if needed) - -#### **Electron Database Location** -```bash -# Linux -rm -rf ~/.config/TimeSafari/* - -# macOS -rm -rf ~/Library/Application\ Support/TimeSafari/* - -# Windows -rmdir /s /q %APPDATA%\TimeSafari -``` - -#### **Web Browser (Custom Data Directory)** -```bash -# Create isolated browser profile -mkdir ~/timesafari-dev-data - -# Start browser with custom profile -google-chrome --user-data-dir=~/timesafari-dev-data - -# Clear when needed -rm -rf ~/timesafari-dev-data -``` - -See the script for complete platform-specific instructions. diff --git a/docs/electron-build-scripts.md b/docs/electron-build-scripts.md new file mode 100644 index 00000000..1370972d --- /dev/null +++ b/docs/electron-build-scripts.md @@ -0,0 +1,181 @@ +# Electron Build Scripts Guide + +**Author**: Matthew Raymer +**Date**: 2025-07-11 +**Status**: **ACTIVE** - Production Ready + +## Overview + +This document clarifies the difference between Electron build scripts that create executable packages versus those that run the app directly. + +## Script Categories + +### 🚀 **Development Scripts (Run App Directly)** + +These scripts build the app and then run it immediately for development: + +```bash +# Development mode - runs app directly +npm run build:electron:dev + +# Test mode - runs app directly +npm run build:electron:test + +# Production mode - runs app directly +npm run build:electron:prod +``` + +### 📦 **Package Build Scripts (Create Executables)** + +These scripts build executable packages that can be distributed and run by users: + +#### **Platform-Specific Executables** +```bash +# Windows executable (.exe) +npm run build:electron:windows +npm run build:electron:windows:dev +npm run build:electron:windows:test +npm run build:electron:windows:prod + +# macOS app bundle (.app) +npm run build:electron:mac +npm run build:electron:mac:dev +npm run build:electron:mac:test +npm run build:electron:mac:prod + +# Linux executable +npm run build:electron:linux +npm run build:electron:linux:dev +npm run build:electron:linux:test +npm run build:electron:linux:prod +``` + +#### **Package Formats** +```bash +# Linux AppImage (portable executable) +npm run build:electron:appimage +npm run build:electron:appimage:dev +npm run build:electron:appimage:test +npm run build:electron:appimage:prod + +# Linux DEB package (installable) +npm run build:electron:deb +npm run build:electron:deb:dev +npm run build:electron:deb:test +npm run build:electron:deb:prod + +# macOS DMG package (installable) +npm run build:electron:dmg +npm run build:electron:dmg:dev +npm run build:electron:dmg:test +npm run build:electron:dmg:prod +``` + +## Output Locations + +### **Development Scripts** +- Run the app directly in development mode +- No files created for distribution +- App runs immediately after build + +### **Package Scripts** +- Create executable files in `electron/dist/` +- Files can be distributed to users +- Users can run the executables by hand + +#### **Package Output Examples** +```bash +# AppImage +electron/dist/TimeSafari-1.0.3-beta.AppImage + +# DEB package +electron/dist/TimeSafari_1.0.3-beta_amd64.deb + +# DMG package +electron/dist/TimeSafari-1.0.3-beta.dmg + +# Windows executable +electron/dist/TimeSafari Setup 1.0.3-beta.exe +``` + +## Usage Examples + +### **Development Workflow** +```bash +# Start development (runs app directly) +npm run build:electron:dev + +# Test with production build (runs app directly) +npm run build:electron:test +``` + +### **Distribution Workflow** +```bash +# Build AppImage for Linux distribution +npm run build:electron:appimage:prod + +# Build DMG for macOS distribution +npm run build:electron:dmg:prod + +# Build Windows installer +npm run build:electron:windows:prod +``` + +### **Testing Packages** +```bash +# Build test version of AppImage +npm run build:electron:appimage:test + +# Test the generated executable +./electron/dist/TimeSafari-1.0.3-beta.AppImage +``` + +## Key Differences + +| Script Type | Purpose | Output | User Action | +|-------------|---------|--------|-------------| +| Development | Run app directly | None | App starts automatically | +| Package | Create executable | `electron/dist/` | User runs executable by hand | + +## Best Practices + +### **For Development** +- Use `npm run build:electron:dev` for daily development +- Use `npm run build:electron:test` for testing production builds +- App runs immediately after build + +### **For Distribution** +- Use `npm run build:electron:*:prod` for production packages +- Test packages before distribution +- Users install/run the generated executables + +### **For Testing** +- Use `npm run build:electron:*:test` for test packages +- Verify executables work on target platforms +- Test installation and uninstallation + +## Troubleshooting + +### **Package Build Issues** +```bash +# Check if package was created +ls -la electron/dist/ + +# Verify package integrity +file electron/dist/*.AppImage +file electron/dist/*.deb +file electron/dist/*.dmg +``` + +### **Development Issues** +```bash +# Clean and rebuild +npm run clean:electron +npm run build:electron:dev +``` + +--- + +**Last Updated**: 2025-07-11 +**Version**: 1.0.3-beta +**Status**: Production Ready \ No newline at end of file