From b5ee6e061acf1388aef777ddcd9a2bf84bd6ed57 Mon Sep 17 00:00:00 2001 From: "Rodrigo Rodriguez (Pragmatismo)" Date: Wed, 4 Feb 2026 13:54:24 -0300 Subject: [PATCH] Update: delete PROMPT.md and update README.md --- PROMPT.md | 193 ----------------------------------- README.md | 297 ++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 257 insertions(+), 233 deletions(-) delete mode 100644 PROMPT.md diff --git a/PROMPT.md b/PROMPT.md deleted file mode 100644 index 871a493..0000000 --- a/PROMPT.md +++ /dev/null @@ -1,193 +0,0 @@ -# BotApp Development Guide - -**Version:** 6.2.0 -**Purpose:** Desktop application wrapper (Tauri 2) - ---- - -## ZERO TOLERANCE POLICY - -**EVERY SINGLE WARNING MUST BE FIXED. NO EXCEPTIONS.** - ---- - -## ❌ ABSOLUTE PROHIBITIONS - -``` -❌ NEVER use #![allow()] or #[allow()] in source code -❌ NEVER use _ prefix for unused variables - DELETE or USE them -❌ NEVER use .unwrap() - use ? or proper error handling -❌ NEVER use .expect() - use ? or proper error handling -❌ NEVER use panic!() or unreachable!() -❌ NEVER use todo!() or unimplemented!() -❌ NEVER leave unused imports or dead code -❌ NEVER add comments - code must be self-documenting -``` - ---- - -## 🔐 SECURITY - TAURI SPECIFIC - -``` -❌ NEVER trust user input from IPC commands -❌ NEVER expose filesystem paths to frontend without validation -❌ NEVER store secrets in plain text or localStorage -❌ NEVER disable CSP in tauri.conf.json for production -❌ NEVER use allowlist: all in Tauri configuration -``` - -### Path Validation - -```rust -// ❌ WRONG - trusting user path -#[tauri::command] -async fn read_file(path: String) -> Result { - std::fs::read_to_string(path).map_err(|e| e.to_string()) -} - -// ✅ CORRECT - validate and sandbox paths -#[tauri::command] -async fn read_file(app: tauri::AppHandle, filename: String) -> Result { - let safe_name = filename - .chars() - .filter(|c| c.is_alphanumeric() || *c == '.' || *c == '-') - .collect::(); - if safe_name.contains("..") { - return Err("Invalid filename".into()); - } - let base_dir = app.path().app_data_dir().map_err(|e| e.to_string())?; - let full_path = base_dir.join(&safe_name); - std::fs::read_to_string(full_path).map_err(|e| e.to_string()) -} -``` - ---- - -## 🏗️ ARCHITECTURE - -### Structure - -``` -botapp/ -├── src/ -│ └── main.rs # Rust backend, Tauri commands -├── ui/ -│ └── app-guides/ # App-specific HTML -├── js/ -│ └── app-extensions.js # JavaScript extensions -├── icons/ # App icons (all sizes) -├── tauri.conf.json # Tauri configuration -└── Cargo.toml -``` - -### Communication Flow - -``` -Native UI (HTML/CSS/JS) - ↓ Tauri IPC (invoke) -Rust #[tauri::command] - ↓ HTTP (reqwest) -botserver API - ↓ -Business Logic + Database -``` - ---- - -## 🔧 TAURI COMMAND PATTERN - -```rust -use tauri::command; - -#[command] -pub async fn my_command( - window: tauri::Window, - param: String, -) -> Result { - if param.is_empty() || param.len() > 1000 { - return Err("Invalid parameter".into()); - } - Ok(MyResponse { /* ... */ }) -} - -fn main() { - tauri::Builder::default() - .invoke_handler(tauri::generate_handler![ - my_command, - ]) - .run(tauri::generate_context!()) - .map_err(|e| format!("error running app: {e}"))?; -} -``` - -### JavaScript Invocation - -```javascript -const result = await window.__TAURI__.invoke('my_command', { - param: 'value' -}); -``` - ---- - -## 🎨 ICONS - MANDATORY - -**NEVER generate icons with LLM. Use official SVG icons from `botui/ui/suite/assets/icons/`** - -Required icon sizes in `icons/`: -``` -icon.ico # Windows (256x256) -icon.icns # macOS -icon.png # Linux (512x512) -32x32.png -128x128.png -128x128@2x.png -``` - ---- - -## ⚙️ CONFIGURATION (tauri.conf.json) - -```json -{ - "$schema": "https://schema.tauri.app/config/2", - "productName": "General Bots", - "version": "6.2.0", - "identifier": "br.com.pragmatismo.botapp", - "build": { - "devUrl": "http://localhost:3000", - "frontendDist": "../botui/ui/suite" - }, - "app": { - "security": { - "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'" - } - } -} -``` - ---- - -## 📦 KEY DEPENDENCIES - -| Library | Version | Purpose | -|---------|---------|---------| -| tauri | 2 | Desktop framework | -| tauri-plugin-dialog | 2 | File dialogs | -| tauri-plugin-opener | 2 | URL/file opener | -| botlib | path | Shared types | -| reqwest | 0.12 | HTTP client | -| tokio | 1.41 | Async runtime | - ---- - -## 🔑 REMEMBER - -- **ZERO WARNINGS** - Every clippy warning must be fixed -- **NO ALLOW IN CODE** - Never use #[allow()] in source files -- **NO DEAD CODE** - Delete unused code -- **NO UNWRAP/EXPECT** - Use ? operator -- **Security** - Minimal allowlist, validate ALL inputs -- **Desktop-only features** - Shared logic in botserver -- **Tauri APIs** - No direct fs access from JS -- **Version 6.2.0** - do not change without approval \ No newline at end of file diff --git a/README.md b/README.md index 7341a09..d8e7bc2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,17 @@ # BotApp - General Bots Desktop Application -BotApp is the Tauri-based desktop wrapper for General Bots, providing native desktop and mobile capabilities on top of the pure web UI from [botui](https://github.com/GeneralBots/botui). +**Version:** 6.2.0 +**Purpose:** Desktop application wrapper (Tauri 2) + +--- + +## Overview + +BotApp is the Tauri-based desktop wrapper for General Bots, providing native desktop and mobile capabilities on top of the pure web UI from [botui](https://github.com/GeneralBots/botui). It extends the web interface with native file system access, system tray functionality, and desktop-specific features while maintaining a clean separation from the pure web UI. + +For comprehensive documentation, see **[docs.pragmatismo.com.br](https://docs.pragmatismo.com.br)** or the **[BotBook](../botbook)** for detailed guides, API references, and tutorials. + +--- ## Architecture @@ -25,6 +36,20 @@ This separation allows: - Clean dependency management (web users don't need Tauri) - App-specific features only in the native app +### Communication Flow + +``` +Native UI (HTML/CSS/JS) + ↓ Tauri IPC (invoke) +Rust #[tauri::command] + ↓ HTTP (reqwest) +botserver API + ↓ +Business Logic + Database +``` + +--- + ## Features BotApp adds these native capabilities to botui: @@ -35,35 +60,39 @@ BotApp adds these native capabilities to botui: - **Desktop Notifications**: Native OS notifications - **App Settings**: Desktop-specific configuration +--- + ## Project Structure ``` botapp/ -├── Cargo.toml # Rust dependencies (includes Tauri) -├── build.rs # Tauri build script -├── tauri.conf.json # Tauri configuration ├── src/ -│ ├── main.rs # Tauri entry point -│ ├── lib.rs # Library exports +│ ├── main.rs # Rust backend, Tauri commands +│ ├── lib.rs # Library exports │ └── desktop/ -│ ├── mod.rs # Desktop module -│ ├── drive.rs # File system commands -│ └── tray.rs # System tray functionality +│ ├── mod.rs # Desktop module organization +│ ├── drive.rs # File system commands +│ └── tray.rs # System tray functionality ├── ui/ -│ └── app-guides/ # App-only HTML content -│ ├── local-files.html -│ └── native-settings.html -└── js/ - └── app-extensions.js # Injected into botui's suite +│ └── app-guides/ # App-specific HTML +├── js/ +│ └── app-extensions.js # JavaScript extensions +├── icons/ # App icons (all sizes) +├── tauri.conf.json # Tauri configuration +└── Cargo.toml ``` -## Prerequisites +--- + +## Development + +### Prerequisites - Rust 1.70+ - Node.js 18+ (for Tauri CLI) - Tauri CLI: `cargo install tauri-cli` -### Platform-specific +#### Platform-specific **Linux:** ```bash @@ -78,7 +107,7 @@ xcode-select --install **Windows:** - Visual Studio Build Tools with C++ workload -## Development +### Getting Started 1. Clone both repositories: ```bash @@ -98,6 +127,8 @@ cd botapp cargo tauri dev ``` +--- + ## Building ### Debug Build @@ -112,7 +143,134 @@ cargo tauri build Binaries will be in `target/release/bundle/`. -## How App Extensions Work +--- + +## 🖥️ Tauri Command Pattern + +```rust +use tauri::command; + +#[command] +pub async fn my_command( + window: tauri::Window, + param: String, +) -> Result { + if param.is_empty() || param.len() > 1000 { + return Err("Invalid parameter".into()); + } + Ok(MyResponse { /* ... */ }) +} + +fn main() { + tauri::Builder::default() + .invoke_handler(tauri::generate_handler![ + my_command, + ]) + .run(tauri::generate_context!()) + .map_err(|e| format!("error running app: {e}"))?; +} +``` + +### JavaScript Invocation + +```javascript +const result = await window.__TAURI__.invoke('my_command', { + param: 'value' +}); +``` + +### Available Tauri Commands + +| Command | Description | +|---------|-------------| +| `list_files` | List directory contents | +| `upload_file` | Copy file with progress | +| `create_folder` | Create new directory | +| `delete_path` | Delete file or folder | +| `get_home_dir` | Get user's home directory | + +--- + +## 🔐 Security Directives + +### Path Validation + +```rust +// ❌ WRONG - trusting user path +#[tauri::command] +async fn read_file(path: String) -> Result { + std::fs::read_to_string(path).map_err(|e| e.to_string()) +} + +// ✅ CORRECT - validate and sandbox paths +#[tauri::command] +async fn read_file(app: tauri::AppHandle, filename: String) -> Result { + let safe_name = filename + .chars() + .filter(|c| c.is_alphanumeric() || *c == '.' || *c == '-') + .collect::(); + if safe_name.contains("..") { + return Err("Invalid filename".into()); + } + let base_dir = app.path().app_data_dir().map_err(|e| e.to_string())?; + let full_path = base_dir.join(&safe_name); + std::fs::read_to_string(full_path).map_err(|e| e.to_string()) +} +``` + +### Security Prohibitions + +``` +❌ NEVER trust user input from IPC commands +❌ NEVER expose filesystem paths to frontend without validation +❌ NEVER store secrets in plain text or localStorage +❌ NEVER disable CSP in tauri.conf.json for production +❌ NEVER use allowlist: all in Tauri configuration +``` + +--- + +## 🎨 Icons - MANDATORY + +**NEVER generate icons with LLM. Use official SVG icons from `botui/ui/suite/assets/icons/`** + +Required icon sizes in `icons/`: +``` +icon.ico # Windows (256x256) +icon.icns # macOS +icon.png # Linux (512x512) +32x32.png +128x128.png +128x128@2x.png +``` + +All icons use `stroke="currentColor"` for CSS theming. + +--- + +## ⚙️ Configuration (tauri.conf.json) + +```json +{ + "$schema": "https://schema.tauri.app/config/2", + "productName": "General Bots", + "version": "6.2.0", + "identifier": "br.com.pragmatismo.botapp", + "build": { + "devUrl": "http://localhost:3000", + "frontendDist": "../botui/ui/suite" + }, + "app": { + "security": { + "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'" + } + } +} +``` + +--- + +## 🎯 How App Extensions Work BotApp injects `js/app-extensions.js` into botui's suite at runtime. This script: @@ -129,34 +287,63 @@ if (window.BotApp?.isApp) { } ``` -## Tauri Commands +--- -Available Tauri commands (invokable from JS): +## ✅ ZERO TOLERANCE POLICY -| Command | Description | -|---------|-------------| -| `list_files` | List directory contents | -| `upload_file` | Copy file with progress | -| `create_folder` | Create new directory | -| `delete_path` | Delete file or folder | -| `get_home_dir` | Get user's home directory | +**EVERY SINGLE WARNING MUST BE FIXED. NO EXCEPTIONS.** -## Configuration +### Absolute Prohibitions -Edit `tauri.conf.json` to customize: +``` +❌ NEVER use #![allow()] or #[allow()] in source code +❌ NEVER use _ prefix for unused variables - DELETE or USE them +❌ NEVER use .unwrap() - use ? or proper error handling +❌ NEVER use .expect() - use ? or proper error handling +❌ NEVER use panic!() or unreachable!() +❌ NEVER use todo!() or unimplemented!() +❌ NEVER leave unused imports or dead code +❌ NEVER add comments - code must be self-documenting +``` -- `productName`: Application name -- `identifier`: Unique app identifier -- `build.devUrl`: URL for development (default: `http://localhost:3000`) -- `build.frontendDist`: Path to botui's UI (default: `../botui/ui/suite`) +### Code Patterns -## License +```rust +// ❌ WRONG +let value = something.unwrap(); -AGPL-3.0 - See [LICENSE](LICENSE) for details. +// ✅ CORRECT +let value = something?; +let value = something.ok_or_else(|| Error::NotFound)?; -## Testing and Safety Tooling +// Use Self in Impl Blocks +impl MyStruct { + fn new() -> Self { Self { } } // ✅ Not MyStruct +} -BotApp follows General Bots' commitment to code quality and safety. The following tools are available for verification: +// Derive Eq with PartialEq +#[derive(PartialEq, Eq)] // ✅ Always both +struct MyStruct { } +``` + +--- + +## 📦 Key Dependencies + +| Library | Version | Purpose | +|---------|---------|---------| +| tauri | 2 | Desktop framework | +| tauri-plugin-dialog | 2 | File dialogs | +| tauri-plugin-opener | 2 | URL/file opener | +| botlib | workspace | Shared types | +| reqwest | 0.12 | HTTP client | +| tokio | 1.41 | Async runtime | + +--- + +## 🧪 Testing and Safety Tooling + +BotApp follows General Bots' commitment to code quality and safety. ### Standard Testing @@ -201,10 +388,40 @@ Ferrocene is a qualified Rust compiler for safety-critical systems (ISO 26262, I For most use cases, comprehensive testing with the tools above provides adequate confidence. -See [Testing & Safety Tooling](../botbook/src/07-gbapp/testing-safety.md) for complete documentation. +--- -## Related Projects +## 📚 Documentation + +For complete documentation, guides, and API references: + +- **[docs.pragmatismo.com.br](https://docs.pragmatismo.com.br)** - Full online documentation +- **[BotBook](../botbook)** - Local comprehensive guide with tutorials and examples +- **[Testing & Safety Tooling](../botbook/src/07-gbapp/testing-safety.md)** - Complete testing documentation + +--- + +## 🔑 Remember + +- **ZERO WARNINGS** - Every clippy warning must be fixed +- **NO ALLOW IN CODE** - Never use #[allow()] in source files +- **NO DEAD CODE** - Delete unused code +- **NO UNWRAP/EXPECT** - Use ? operator +- **Security** - Minimal allowlist, validate ALL inputs +- **Desktop-only features** - Shared logic in botserver +- **Tauri APIs** - No direct fs access from JS +- **Official icons** - Use icons from botui/ui/suite/assets/icons/ +- **Version 6.2.0** - Do not change without approval + +--- + +## 🔗 Related Projects - [botui](https://github.com/GeneralBots/botui) - Pure web UI - [botserver](https://github.com/GeneralBots/botserver) - Backend server -- [botlib](https://github.com/GeneralBots/botlib) - Shared Rust library \ No newline at end of file +- [botlib](https://github.com/GeneralBots/botlib) - Shared Rust library + +--- + +## License + +AGPL-3.0 - See [LICENSE](LICENSE) for details. \ No newline at end of file