aegis-framework 0.1.0 → 0.1.1

package/aegis/cli/cli.py

@@ -434,48 +434,266 @@ console.log('✅ Preload configured');
         # README
         readme_content = f'''# {project_name}
 
-An application built with [Aegis Framework](https://github.com/your-repo/aegis).
+An application built with [Aegis Framework](https://github.com/Diegopam/aegis-framework) - the lightweight alternative to Electron!
 
-## Getting Started
+## 🚀 Quick Start
 
 ```bash
-# Development mode
+# Development mode (with hot-reload)
 aegis dev
 
-# Build AppImage
+# Run in production mode  
+aegis run
+
+# Build AppImage (~200KB!)
 aegis build
 ```
 
-## Project Structure
+## 📁 Project Structure
 
 ```
 {project_name}/
-├── aegis.config.json    # Project configuration
+├── aegis.config.json    # App configuration (size, title, etc.)
 ├── src/
-│   ├── index.html       # Main HTML
-│   ├── styles.css       # Styles
-│   ├── app.js           # JavaScript
-│   └── preload.js       # Security configuration
+│   ├── index.html       # Main HTML entry point
+│   ├── styles.css       # Your styles
+│   ├── app.js           # Your JavaScript code
+│   └── preload.js       # Security: control which APIs are exposed
 └── assets/
-    └── icon.png         # App icon
+    └── icon.png         # App icon (256x256 recommended)
 ```
 
-## Aegis API
+## 🔌 Aegis API Reference
+
+### File Operations
 
 ```javascript
-// Read files
-const content = await Aegis.read({{ path: '.', file: 'data.txt' }});
+// Read directory contents
+const dir = await Aegis.read({{ path: '/home/user' }});
+console.log(dir.entries);  // [{{ name: 'file.txt', isFile: true, size: 1234 }}, ...]
+
+// Read file content
+const file = await Aegis.read({{ path: '/home/user', file: 'data.txt' }});
+console.log(file.content);
+
+// Write file
+await Aegis.write({{
+    path: '/home/user',
+    file: 'output.txt',
+    content: 'Hello, Aegis!'
+}});
+
+// Check if file/directory exists
+const info = await Aegis.exists({{ path: '/home/user/file.txt' }});
+if (info.exists && info.isFile) {{
+    console.log('File exists!');
+}}
+
+// Create directory
+await Aegis.mkdir({{ path: '/home/user/new-folder' }});
+
+// Delete file or directory
+await Aegis.remove({{ path: '/home/user/old-file.txt' }});
+await Aegis.remove({{ path: '/home/user/old-folder', recursive: true }});
+
+// Copy file or directory
+await Aegis.copy({{
+    src: '/home/user/file.txt',
+    dest: '/home/user/backup/file.txt'
+}});
+
+// Move/rename file or directory
+await Aegis.move({{
+    src: '/home/user/old-name.txt',
+    dest: '/home/user/new-name.txt'
+}});
+```
 
-// Write files
-await Aegis.write({{ path: '.', file: 'output.txt', content: 'Hello!' }});
+### Execute Commands
 
-// Run commands
+```javascript
+// Run shell command
 const result = await Aegis.run({{ sh: 'ls -la' }});
+console.log(result.output);
+console.log(result.exitCode);
+
+// Run Python code
+const pyResult = await Aegis.run({{ py: 'print(2 + 2)' }});
+console.log(pyResult.output);  // "4"
+
+// Run async command with streaming output (no UI freeze!)
+await Aegis.runAsync(
+    {{ sh: 'apt update' }},
+    (progress) => {{
+        console.log(progress.line);  // Each line as it comes
+    }}
+);
+```
+
+### Dialogs
 
-// Dialogs
-await Aegis.dialog.message({{ type: 'info', title: 'Hello', message: 'World!' }});
+```javascript
+// Info dialog
+await Aegis.dialog.message({{
+    type: 'info',
+    title: 'Success',
+    message: 'Operation completed!'
+}});
+
+// Confirmation dialog
+const confirm = await Aegis.dialog.message({{
+    type: 'question',
+    title: 'Confirm',
+    message: 'Are you sure?',
+    buttons: 'yesno'
+}});
+if (confirm.response) {{
+    // User clicked Yes
+}}
+
+// Open file dialog
+const file = await Aegis.dialog.open({{
+    title: 'Select a file',
+    filters: [{{ name: 'Images', extensions: ['png', 'jpg', 'gif'] }}]
+}});
+console.log(file.path);
+
+// Save file dialog
+const savePath = await Aegis.dialog.save({{
+    title: 'Save as',
+    defaultName: 'document.txt'
+}});
+```
+
+### Download with Progress
+
+```javascript
+// Download file with progress bar
+await Aegis.download(
+    {{
+        url: 'https://example.com/file.zip',
+        dest: '/home/user/downloads/file.zip'
+    }},
+    (progress) => {{
+        const percent = progress.percent.toFixed(1);
+        progressBar.style.width = percent + '%';
+        statusText.textContent = `${{progress.downloaded}} / ${{progress.total}} bytes`;
+    }}
+);
 ```
 
+### App Control
+
+```javascript
+// Window controls
+Aegis.app.minimize();
+Aegis.app.maximize();
+Aegis.app.quit();
+
+// Get system paths (localized for your language!)
+const home = await Aegis.app.getPath({{ name: 'home' }});
+const docs = await Aegis.app.getPath({{ name: 'documents' }});  // Returns "Documentos" on pt-BR
+const downloads = await Aegis.app.getPath({{ name: 'downloads' }});
+// Also: desktop, music, pictures, videos
+```
+
+### Window Control (Frameless Windows)
+
+```javascript
+// Make element draggable for window movement
+Aegis.window.moveBar('#titlebar', {{ exclude: '.btn-close' }});
+
+// Setup resize handles
+Aegis.window.resizeHandles({{
+    '.resize-n': 'n',
+    '.resize-s': 's',
+    '.resize-se': 'se',
+    // Options: n, s, e, w, ne, nw, se, sw
+}});
+
+// Get/set window size
+const size = await Aegis.window.getSize();
+await Aegis.window.setSize({{ width: 1024, height: 768 }});
+
+// Get/set window position
+const pos = await Aegis.window.getPosition();
+await Aegis.window.setPosition({{ x: 100, y: 100 }});
+```
+
+## 🔒 Security (preload.js)
+
+Control which APIs your app can access:
+
+```javascript
+// src/preload.js
+Aegis.expose([
+    'read',      // File reading
+    'write',     // File writing
+    'run',       // Command execution
+    'dialog',    // Native dialogs
+    'app',       // App control
+    'window',    // Window control
+    'download',  // Download with progress
+    'exists',    // File existence
+    'mkdir',     // Create directories
+    'remove',    // Delete files
+    'copy',      // Copy files
+    'move'       // Move/rename files
+]);
+
+// For maximum security, only expose what you need!
+// If you omit 'run', the app cannot execute shell commands
+```
+
+## ⚙️ Configuration (aegis.config.json)
+
+```json
+{{
+    "name": "{project_name}",
+    "title": "My Awesome App",
+    "version": "1.0.0",
+    "main": "src/index.html",
+    "preload": "src/preload.js",
+    "width": 1200,
+    "height": 800,
+    "resizable": true,
+    "frame": true,
+    "icon": "assets/icon.png"
+}}
+```
+
+| Option | Description |
+|--------|-------------|
+| `frame` | Set to `false` for frameless window (custom titlebar) |
+| `resizable` | Allow window resizing |
+| `width/height` | Initial window size |
+| `devTools` | Enable right-click → Inspect Element |
+
+## 📦 Building AppImage
+
+```bash
+aegis build
+```
+
+This creates a portable AppImage (~200KB!) in the `dist/` folder.
+
+**Note:** The AppImage requires `python3-gi` and `gir1.2-webkit2-4.1` on the target system.
+
+## 🆚 Why Aegis over Electron?
+
+| Aspect | Electron | Aegis |
+|--------|----------|-------|
+| App Size | ~150 MB | **~200 KB** |
+| Backend | Node.js | Python |
+| Renderer | Chromium (bundled) | WebKit2GTK (system) |
+| RAM Usage | High (~100MB+) | Low (~30MB) |
+| Platform | Cross-platform | Linux |
+
+## 📚 Learn More
+
+- [Aegis GitHub](https://github.com/Diegopam/aegis-framework)
+- [npm Package](https://www.npmjs.com/package/aegis-framework)
+
 ## License
 
 MIT

package/aegis/core/window.py

@@ -10,6 +10,9 @@ gi.require_version('WebKit2', '4.1')
 from gi.repository import Gtk, WebKit2, Gdk, GLib
 import json
 import os
+import threading
+import urllib.request
+import shutil
 
 
 class AegisWindow(Gtk.Window):
@@ -114,12 +117,17 @@ class AegisWindow(Gtk.Window):
             
             print(f"[Aegis] Action: {action}, Payload: {payload}")
             
-            # Process action and get result
-            result = self._process_action(action, payload)
+            # Check if this is an async action
+            async_actions = {'run.async', 'download', 'copy.async'}
             
-            # Send response back to JavaScript
-            if callback_id:
-                self._send_response(callback_id, result)
+            if action in async_actions:
+                # Handle in background thread - response sent via callback
+                self._process_async_action(action, payload, callback_id)
+            else:
+                # Sync action - process and respond immediately
+                result = self._process_action(action, payload)
+                if callback_id:
+                    self._send_response(callback_id, result)
                 
         except Exception as e:
             print(f"[Aegis Bridge] Error: {e}")
@@ -597,6 +605,180 @@ class AegisWindow(Gtk.Window):
         )
         self.content_manager.add_script(user_script)
     
+    # ==================== Async Action Handlers ====================
+    
+    def _process_async_action(self, action, payload, callback_id):
+        """Process async actions in background threads"""
+        handlers = {
+            'run.async': self._handle_run_async,
+            'download': self._handle_download,
+            'copy.async': self._handle_copy_async,
+        }
+        
+        handler = handlers.get(action)
+        if handler:
+            # Start background thread
+            thread = threading.Thread(
+                target=handler,
+                args=(payload, callback_id),
+                daemon=True
+            )
+            thread.start()
+        else:
+            GLib.idle_add(self._send_error, callback_id, f"Unknown async action: {action}")
+    
+    def _send_progress(self, callback_id, progress_data):
+        """Send progress update to JavaScript (must be called via GLib.idle_add)"""
+        response = json.dumps({
+            'callbackId': callback_id,
+            'type': 'progress',
+            'data': progress_data
+        })
+        script = f"window.__aegisProgress({response})"
+        self.webview.evaluate_javascript(script, -1, None, None, None, None, None)
+        return False  # Don't repeat
+    
+    def _handle_run_async(self, payload, callback_id):
+        """Execute command asynchronously with streaming output"""
+        import subprocess
+        
+        try:
+            cmd = payload.get('sh', '')
+            
+            process = subprocess.Popen(
+                cmd,
+                shell=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1
+            )
+            
+            output_lines = []
+            
+            # Stream output line by line
+            for line in process.stdout:
+                output_lines.append(line)
+                GLib.idle_add(self._send_progress, callback_id, {
+                    'type': 'output',
+                    'line': line.rstrip('\n')
+                })
+            
+            process.wait()
+            
+            # Send final result
+            result = {
+                'output': ''.join(output_lines),
+                'exitCode': process.returncode
+            }
+            GLib.idle_add(self._send_response, callback_id, result)
+            
+        except Exception as e:
+            GLib.idle_add(self._send_error, callback_id, str(e))
+    
+    def _handle_download(self, payload, callback_id):
+        """Download file with progress updates"""
+        try:
+            url = payload.get('url')
+            dest = payload.get('dest')
+            
+            # Create request
+            req = urllib.request.Request(url, headers={
+                'User-Agent': 'Aegis/0.1.0'
+            })
+            
+            response = urllib.request.urlopen(req, timeout=30)
+            total_size = int(response.headers.get('Content-Length', 0))
+            downloaded = 0
+            
+            # Ensure destination directory exists
+            os.makedirs(os.path.dirname(dest) or '.', exist_ok=True)
+            
+            with open(dest, 'wb') as f:
+                while True:
+                    chunk = response.read(8192)
+                    if not chunk:
+                        break
+                    
+                    f.write(chunk)
+                    downloaded += len(chunk)
+                    
+                    # Send progress update
+                    progress = {
+                        'downloaded': downloaded,
+                        'total': total_size,
+                        'percent': (downloaded / total_size * 100) if total_size else 0
+                    }
+                    GLib.idle_add(self._send_progress, callback_id, progress)
+            
+            # Send completion
+            result = {
+                'success': True,
+                'path': dest,
+                'size': downloaded
+            }
+            GLib.idle_add(self._send_response, callback_id, result)
+            
+        except Exception as e:
+            GLib.idle_add(self._send_error, callback_id, str(e))
+    
+    def _handle_copy_async(self, payload, callback_id):
+        """Copy files/directories with progress (for large files)"""
+        try:
+            src = payload.get('src')
+            dest = payload.get('dest')
+            
+            if os.path.isdir(src):
+                # Copy directory
+                def copy_with_progress(src_dir, dest_dir):
+                    total_files = sum([len(files) for _, _, files in os.walk(src_dir)])
+                    copied = 0
+                    
+                    for root, dirs, files in os.walk(src_dir):
+                        rel_path = os.path.relpath(root, src_dir)
+                        dest_path = os.path.join(dest_dir, rel_path)
+                        os.makedirs(dest_path, exist_ok=True)
+                        
+                        for file in files:
+                            src_file = os.path.join(root, file)
+                            dest_file = os.path.join(dest_path, file)
+                            shutil.copy2(src_file, dest_file)
+                            copied += 1
+                            
+                            GLib.idle_add(self._send_progress, callback_id, {
+                                'copied': copied,
+                                'total': total_files,
+                                'percent': (copied / total_files * 100) if total_files else 100,
+                                'current': file
+                            })
+                
+                copy_with_progress(src, dest)
+            else:
+                # Copy single file with progress
+                file_size = os.path.getsize(src)
+                copied = 0
+                
+                with open(src, 'rb') as fsrc:
+                    with open(dest, 'wb') as fdest:
+                        while True:
+                            chunk = fsrc.read(8192)
+                            if not chunk:
+                                break
+                            fdest.write(chunk)
+                            copied += len(chunk)
+                            
+                            GLib.idle_add(self._send_progress, callback_id, {
+                                'copied': copied,
+                                'total': file_size,
+                                'percent': (copied / file_size * 100) if file_size else 100
+                            })
+            
+            result = {'success': True, 'src': src, 'dest': dest}
+            GLib.idle_add(self._send_response, callback_id, result)
+            
+        except Exception as e:
+            GLib.idle_add(self._send_error, callback_id, str(e))
+    
     def run(self):
         """Show window and start main loop"""
         self.show_all()

package/aegis/runtime/aegis-api.js

@@ -14,6 +14,7 @@
 
     let callbackId = 0;
     const pendingCallbacks = new Map();
+    const progressCallbacks = new Map();  // For async progress updates
 
     /**
      * Resolve a callback from Python
@@ -22,6 +23,7 @@
         const callback = pendingCallbacks.get(response.callbackId);
         if (callback) {
             pendingCallbacks.delete(response.callbackId);
+            progressCallbacks.delete(response.callbackId);  // Cleanup progress callback
             if (response.success) {
                 callback.resolve(response.data);
             } else {
@@ -30,6 +32,16 @@
         }
     };
 
+    /**
+     * Handle progress updates from Python (for async operations)
+     */
+    window.__aegisProgress = function (response) {
+        const callback = progressCallbacks.get(response.callbackId);
+        if (callback) {
+            callback(response.data);
+        }
+    };
+
     /**
      * Send a message to Python backend
      */
@@ -78,6 +90,41 @@
         };
     }
 
+    /**
+     * Invoke an async action with progress callback
+     * @param {string} action - The action name
+     * @param {object} payload - The payload
+     * @param {function} onProgress - Progress callback function
+     */
+    function invokeWithProgress(action, payload, onProgress) {
+        return new Promise((resolve, reject) => {
+            if (!isAllowed(action)) {
+                reject(new Error(`API '${action}' is not allowed by preload`));
+                return;
+            }
+
+            const id = ++callbackId;
+            pendingCallbacks.set(id, { resolve, reject });
+
+            // Register progress callback if provided
+            if (onProgress && typeof onProgress === 'function') {
+                progressCallbacks.set(id, onProgress);
+            }
+
+            const message = JSON.stringify({
+                action: action,
+                payload: payload,
+                callbackId: id
+            });
+
+            if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.aegis) {
+                window.webkit.messageHandlers.aegis.postMessage(message);
+            } else {
+                reject(new Error('Aegis bridge not available'));
+            }
+        });
+    }
+
     // ==================== Public Aegis API ====================
 
     const Aegis = {
@@ -170,6 +217,74 @@
          */
         copy: guardedInvoke('copy'),
 
+        // ==================== Async Operations with Progress ====================
+
+        /**
+         * Run command asynchronously with streaming output
+         * 
+         * @param {object} options - Command options
+         * @param {string} options.sh - Shell command to execute
+         * @param {function} onProgress - Progress callback, called with each output line
+         * @returns {Promise<{output: string, exitCode: number}>}
+         * 
+         * @example
+         * const result = await Aegis.runAsync(
+         *     { sh: 'apt install htop' },
+         *     (progress) => {
+         *         console.log(progress.line);  // Each line of output
+         *     }
+         * );
+         */
+        runAsync: function (options, onProgress) {
+            return invokeWithProgress('run.async', options, onProgress);
+        },
+
+        /**
+         * Download file with progress updates
+         * 
+         * @param {object} options - Download options
+         * @param {string} options.url - URL to download from
+         * @param {string} options.dest - Destination file path
+         * @param {function} onProgress - Progress callback
+         * @returns {Promise<{success: boolean, path: string, size: number}>}
+         * 
+         * @example
+         * const result = await Aegis.download(
+         *     { 
+         *         url: 'https://example.com/file.zip',
+         *         dest: '/home/user/downloads/file.zip'
+         *     },
+         *     (progress) => {
+         *         progressBar.style.width = progress.percent + '%';
+         *         statusText.textContent = `${progress.downloaded} / ${progress.total}`;
+         *     }
+         * );
+         */
+        download: function (options, onProgress) {
+            return invokeWithProgress('download', options, onProgress);
+        },
+
+        /**
+         * Copy file or directory with progress updates (for large files)
+         * 
+         * @param {object} options - Copy options
+         * @param {string} options.src - Source path
+         * @param {string} options.dest - Destination path
+         * @param {function} onProgress - Progress callback
+         * @returns {Promise<{success: boolean, src: string, dest: string}>}
+         * 
+         * @example
+         * await Aegis.copyAsync(
+         *     { src: '/path/to/large-folder', dest: '/path/to/backup' },
+         *     (progress) => {
+         *         console.log(`${progress.percent.toFixed(1)}% - ${progress.current}`);
+         *     }
+         * );
+         */
+        copyAsync: function (options, onProgress) {
+            return invokeWithProgress('copy.async', options, onProgress);
+        },
+
         /**
          * Move/rename file or directory
          * 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "aegis-framework",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "Lightweight AppImage framework using WebKit2GTK and Python - An alternative to Electron that creates ~200KB apps instead of 150MB!",
     "keywords": [
         "appimage",
@@ -48,4 +48,4 @@
     "engines": {
         "node": ">=14"
     }
-}
+}