From 8e891dfcfe3940c899952c4a8533039f72a7b9f2 Mon Sep 17 00:00:00 2001 From: AndyMik90 Date: Thu, 18 Dec 2025 16:42:00 +0100 Subject: [PATCH] cleanup docs --- UPDATE_SYSTEM_ANALYSIS.md | 312 -------------------------------------- WINDOWS_LINUX_PATH_FIX.md | 139 ----------------- 2 files changed, 451 deletions(-) delete mode 100644 UPDATE_SYSTEM_ANALYSIS.md delete mode 100644 WINDOWS_LINUX_PATH_FIX.md diff --git a/UPDATE_SYSTEM_ANALYSIS.md b/UPDATE_SYSTEM_ANALYSIS.md deleted file mode 100644 index bc30be19..00000000 --- a/UPDATE_SYSTEM_ANALYSIS.md +++ /dev/null @@ -1,312 +0,0 @@ -# Auto Claude Update System Analysis - -## Current State - -The app has **TWO separate update systems** for different components: - -### 1. ✅ Auto Claude Framework Updates (WORKING) - -**What it updates:** The Python framework source code (`auto-claude/` directory) - -**How it works:** -- Checks GitHub Releases API for new versions -- Downloads release tarball -- Extracts and applies update to the bundled source -- Preserves user configuration files (.env, etc.) - -**User Experience:** -- **Settings > Advanced > Updates** section -- Visual update checker with version display -- Release notes rendered in UI -- Progress bar during download -- One-click update button -- Works across all platforms (macOS, Windows, Linux) - -**Files:** -- `auto-claude-ui/src/main/auto-claude-updater.ts` - Main updater module -- `auto-claude-ui/src/main/updater/update-checker.ts` - Update checking -- `auto-claude-ui/src/main/updater/update-installer.ts` - Download & install -- `auto-claude-ui/src/main/ipc-handlers/autobuild-source-handlers.ts` - IPC handlers -- `auto-claude-ui/src/renderer/components/settings/AdvancedSettings.tsx` - UI - -**Status:** ✅ **FULLY FUNCTIONAL** - Non-technical users can update the framework with one click! - ---- - -### 2. ❌ Electron App Updates (NOT IMPLEMENTED) - -**What it updates:** The Electron application itself (Auto Claude UI) - -**Current State:** -- ❌ No `electron-updater` dependency installed -- ❌ No auto-update configuration in electron-builder -- ❌ No update checking in main process -- ❌ No UI for app update notifications -- ❌ Users must manually download new releases from GitHub - -**What users currently need to do:** -1. Go to GitHub Releases page -2. Download the appropriate installer (.dmg, .exe, .AppImage, etc.) -3. Run the installer -4. Manually replace the old app - ---- - -## What Needs to Be Implemented - -To enable automatic Electron app updates for non-technical users, we need to add: - -### 1. Install electron-updater - -```bash -npm install electron-updater -``` - -### 2. Configure electron-builder for Publishing - -Add to `package.json` build config: - -```json -{ - "build": { - "publish": [ - { - "provider": "github", - "owner": "AndyMik90", - "repo": "Auto-Claude" - } - ] - } -} -``` - -### 3. Implement Auto-Update Logic in Main Process - -Create `auto-claude-ui/src/main/app-updater.ts`: - -```typescript -import { autoUpdater } from 'electron-updater'; -import { app, BrowserWindow } from 'electron'; - -export function initializeAppUpdater(mainWindow: BrowserWindow) { - // Configure update checking - autoUpdater.autoDownload = false; // Let user decide - autoUpdater.autoInstallOnAppQuit = true; - - // Check for updates on launch (after 3 seconds) - setTimeout(() => { - autoUpdater.checkForUpdates(); - }, 3000); - - // Check periodically (every 4 hours) - setInterval(() => { - autoUpdater.checkForUpdates(); - }, 4 * 60 * 60 * 1000); - - // Event handlers - autoUpdater.on('update-available', (info) => { - mainWindow.webContents.send('app-update-available', { - version: info.version, - releaseNotes: info.releaseNotes, - releaseDate: info.releaseDate - }); - }); - - autoUpdater.on('update-downloaded', (info) => { - mainWindow.webContents.send('app-update-downloaded', { - version: info.version - }); - }); - - autoUpdater.on('error', (error) => { - console.error('App update error:', error); - }); - - autoUpdater.on('download-progress', (progress) => { - mainWindow.webContents.send('app-update-progress', { - percent: progress.percent, - transferred: progress.transferred, - total: progress.total - }); - }); -} - -// IPC handlers -export function registerAppUpdateHandlers() { - ipcMain.handle('app-update-download', async () => { - await autoUpdater.downloadUpdate(); - }); - - ipcMain.handle('app-update-install', () => { - autoUpdater.quitAndInstall(); - }); - - ipcMain.handle('app-update-check', async () => { - return await autoUpdater.checkForUpdates(); - }); -} -``` - -### 4. Add UI Notification Component - -Create an update banner or modal in the renderer that: -- Shows when app update is available -- Displays version and release notes -- Has "Download Update" button -- Shows download progress -- Has "Install and Restart" button after download - -### 5. Update GitHub Release Workflow - -Ensure GitHub releases are created with proper assets: -- macOS: `.dmg` and `.zip` files + `latest-mac.yml` -- Windows: `.exe` installer + `latest.yml` -- Linux: `.AppImage` and `.deb` + `latest-linux.yml` - -The `latest-*.yml` files are auto-generated by electron-builder and contain update metadata. - ---- - -## Implementation Strategy - -### Option A: Full Auto-Update (Recommended) - -**Pros:** -- Best user experience -- Automatic background downloads -- One-click install -- Industry standard - -**Cons:** -- Requires code signing certificates for production (macOS, Windows) -- Without signing, users get security warnings - -### Option B: Update Notification Only - -**Pros:** -- Simpler implementation -- No code signing required -- User downloads from GitHub (trusted source) - -**Cons:** -- Users still need to manually download and install -- Less convenient than auto-update - -**Implementation:** -```typescript -// Just notify, don't auto-download -autoUpdater.autoDownload = false; - -autoUpdater.on('update-available', (info) => { - // Show notification with link to GitHub Releases - mainWindow.webContents.send('app-update-available', { - version: info.version, - downloadUrl: `https://github.com/AndyMik90/Auto-Claude/releases/tag/v${info.version}` - }); -}); -``` - ---- - -## Development vs Production - -**Important:** `electron-updater` only works in **packaged apps**, not in development mode. - -During development: -```typescript -if (app.isPackaged) { - initializeAppUpdater(mainWindow); -} else { - console.log('[Dev] Auto-updater disabled in development mode'); -} -``` - ---- - -## Code Signing Requirements - -For production auto-updates without security warnings: - -### macOS -- Requires Apple Developer account ($99/year) -- Code signing certificate -- Notarization with Apple - -### Windows -- Requires code signing certificate (~$200-400/year) -- Without: Windows SmartScreen warnings - -### Linux -- No code signing required -- Users may need to mark `.AppImage` as executable - ---- - -## Testing Auto-Updates - -1. **Local Testing:** - - Build and package: `npm run package` - - Create local update server or use GitHub Releases - - Test with different versions - -2. **GitHub Releases Testing:** - - Create a draft release on GitHub - - Publish with version tag (e.g., `v2.4.0`) - - electron-builder automatically uploads assets - - Test with previous version installed - ---- - -## Recommended Next Steps - -1. **Phase 1: Add Update Notification** (Quick win) - - Install `electron-updater` - - Add basic update checking - - Show notification with link to GitHub Releases - - No auto-download, users download manually - -2. **Phase 2: Enable Auto-Download** (Better UX) - - Add download progress UI - - Enable auto-download of updates - - Add "Install and Restart" button - -3. **Phase 3: Code Signing** (Production ready) - - Acquire code signing certificates - - Configure signing in electron-builder - - Notarize macOS builds - - Sign Windows builds - ---- - -## Current Framework Update Flow (Already Working!) - -For reference, here's how the existing Auto Claude framework updater works: - -1. User opens **Settings > Advanced > Updates** -2. App checks GitHub Releases API -3. If update available, shows version + release notes -4. User clicks "Download Update" -5. Progress bar shows download status -6. Update is extracted and applied to bundled source -7. User configuration (.env) is preserved -8. Done - no restart needed! - -**This same UX could be replicated for app updates!** - ---- - -## Summary - -| Component | Status | User Experience | -|-----------|--------|-----------------| -| Auto Claude Framework | ✅ Working | One-click update in Settings | -| Electron App (UI) | ❌ Missing | Must download from GitHub manually | - -**Recommendation:** Implement electron-updater with update notifications (Phase 1) as a quick win. This will enable non-technical users to update the app without using git or terminal commands. - -**Estimated effort:** -- Phase 1 (Notifications): 2-4 hours -- Phase 2 (Auto-download): 2-3 hours -- Phase 3 (Code signing): Varies by platform - -The existing framework updater code provides an excellent reference for the UI implementation! diff --git a/WINDOWS_LINUX_PATH_FIX.md b/WINDOWS_LINUX_PATH_FIX.md deleted file mode 100644 index 60cb1bf2..00000000 --- a/WINDOWS_LINUX_PATH_FIX.md +++ /dev/null @@ -1,139 +0,0 @@ -# Windows/Linux Source Path Detection Fix - -## Problem - -On Windows and Linux, when initializing a project, users were getting a "Source path not configured" error even though the `auto-claude` source directory exists. This error did not occur on macOS. - -## Root Cause - -The `detectAutoBuildSourcePath()` function in two files was using path resolution logic that worked on macOS in development mode but failed on Windows/Linux, especially in production/packaged builds. The function was trying to auto-detect where the Auto Claude framework source code (`auto-claude/` directory) is located, but the paths resolved differently across platforms. - -## Changes Made - -### 1. Enhanced Path Detection Logic - -Updated `detectAutoBuildSourcePath()` in two files: -- `auto-claude-ui/src/main/ipc-handlers/settings-handlers.ts` -- `auto-claude-ui/src/main/ipc-handlers/project-handlers.ts` - -**Key improvements:** - -1. **Platform-aware path detection**: Separates development vs production mode using `is.dev` from `@electron-toolkit/utils` - -2. **More comprehensive path checking**: - - **Development mode**: Checks multiple relative paths from `__dirname`, `process.cwd()`, and parent directories - - **Production mode**: Checks paths relative to `app.getAppPath()`, `process.resourcesPath`, and multiple levels up - -3. **Debug logging**: Added detailed logging that can be enabled with `AUTO_CLAUDE_DEBUG=1` environment variable - -4. **Better error messages**: Console warnings now guide users to enable debug mode if auto-detection fails - -## Testing on Windows/Linux - -### 1. Run with Debug Logging - -Set the environment variable to see detailed path checking: - -**Windows (PowerShell):** -```powershell -$env:AUTO_CLAUDE_DEBUG="1" -.\Auto-Claude.exe -``` - -**Windows (Command Prompt):** -```cmd -set AUTO_CLAUDE_DEBUG=1 -Auto-Claude.exe -``` - -**Linux:** -```bash -AUTO_CLAUDE_DEBUG=1 ./Auto-Claude -``` - -### 2. Check Console Output - -The debug output will show: -- Current platform (win32/linux/darwin) -- Whether running in dev or production mode -- All paths being checked -- Which paths exist and which don't -- Whether auto-detection succeeded - -Example debug output: -``` -[detectAutoBuildSourcePath] Platform: win32 -[detectAutoBuildSourcePath] Is dev: false -[detectAutoBuildSourcePath] __dirname: C:\Program Files\Auto-Claude\resources\app.asar\out\main -[detectAutoBuildSourcePath] app.getAppPath(): C:\Program Files\Auto-Claude\resources\app.asar -[detectAutoBuildSourcePath] process.cwd(): C:\Program Files\Auto-Claude -[detectAutoBuildSourcePath] Checking paths: [...] -[detectAutoBuildSourcePath] Checking C:\Program Files\auto-claude: ✗ not found -[detectAutoBuildSourcePath] Checking C:\auto-claude: ✓ FOUND -[detectAutoBuildSourcePath] Auto-detected source path: C:\auto-claude -``` - -### 3. Manual Configuration (Fallback) - -If auto-detection still fails, users can manually configure the path: - -1. Open **App Settings** in Auto Claude UI -2. Go to the **General** tab -3. Set **Auto Claude Source Path** to the location of your `auto-claude` directory -4. Click **Save** - -Example paths: -- Windows: `C:\Users\YourName\Projects\autonomous-coding\auto-claude` -- Linux: `/home/yourname/projects/autonomous-coding/auto-claude` - -## What Gets Checked - -The function now checks these paths in order: - -### Development Mode (`is.dev = true`): -1. `__dirname/../../../auto-claude` - From out/main up 3 levels -2. `__dirname/../../auto-claude` - From out/main up 2 levels -3. `process.cwd()/auto-claude` - From current working directory -4. `process.cwd()/../auto-claude` - From parent of cwd - -### Production Mode (`is.dev = false`): -1. `app.getAppPath()/../auto-claude` - Sibling to app -2. `app.getAppPath()/../../auto-claude` - Up 2 from app -3. `app.getAppPath()/../../../auto-claude` - Up 3 from app -4. `process.resourcesPath/../auto-claude` - Relative to resources -5. `process.resourcesPath/../../auto-claude` - Up 2 from resources - -### All Modes: -- `process.cwd()/auto-claude` - Last resort fallback - -## Verification - -For each path, the function checks: -1. Does the directory exist? -2. Does `VERSION` file exist inside it? - -Both must be true for a path to be considered valid. - -## Build Verification - -The changes have been compiled and tested: -``` -✓ Built successfully with no errors -✓ All TypeScript files compiled -✓ Electron app bundle created -``` - -## Next Steps - -1. **Test on Windows**: Have Windows users test the updated build with `AUTO_CLAUDE_DEBUG=1` -2. **Test on Linux**: Have Linux users test the updated build with `AUTO_CLAUDE_DEBUG=1` -3. **Collect feedback**: If issues persist, the debug output will help identify the correct path patterns -4. **Update documentation**: Add troubleshooting section to main README if needed - -## Related Files - -- `auto-claude-ui/src/main/ipc-handlers/settings-handlers.ts` -- `auto-claude-ui/src/main/ipc-handlers/project-handlers.ts` -- `auto-claude-ui/src/main/project-initializer.ts` -- `auto-claude-ui/src/renderer/App.tsx` (shows the error dialog) -- `auto-claude-ui/src/renderer/components/Sidebar.tsx` (shows the error dialog)