tauri-plugin-debug-tools 0.1.0

package/skills/debug-tauri/references/LOGGING.md

@@ -0,0 +1,195 @@
+# Logging with tauri-plugin-log
+
+Official Tauri logging plugin integration for automatic console collection and structured logging.
+
+## Quick Start
+
+```typescript
+import { logger } from "tauri-plugin-debug-tools/logAdapter";
+
+// Initialize once at app startup
+const detach = await logger.initialize();
+
+// Use structured logging
+logger.trace("Detailed trace information");
+logger.debug("Debug information");
+logger.info("Informational message");
+logger.warn("Warning message");
+logger.error("Error occurred");
+
+// Cleanup on app shutdown (optional)
+detach();
+```
+
+## Configuration
+
+Plugin is pre-configured in `src/lib.rs` with the following settings:
+
+```rust
+tauri_plugin_log::Builder::new()
+    .targets([
+        Target::new(TargetKind::Stdout),           // Console output
+        Target::new(TargetKind::LogDir {
+            file_name: Some("debug.log".to_string())
+        }),                                         // File logging
+        Target::new(TargetKind::Webview),          // WebView console
+    ])
+    .max_file_size(50_000)                         // 50KB auto-rotation
+    .build()
+```
+
+## Log File Locations
+
+Platform-specific paths where logs are automatically saved:
+
+### macOS
+
+```
+~/Library/Logs/{bundle_identifier}/debug.log
+```
+
+Example: `~/Library/Logs/com.example.myapp/debug.log`
+
+### Linux
+
+```
+~/.local/share/{bundle_identifier}/logs/debug.log
+```
+
+Example: `~/.local/share/com.example.myapp/logs/debug.log`
+
+### Windows
+
+```
+{FOLDERID_LocalAppData}\{bundle_identifier}\logs\debug.log
+```
+
+Example: `C:\Users\Username\AppData\Local\com.example.myapp\logs\debug.log`
+
+## Log Levels
+
+Available log levels in order of severity:
+
+1. **TRACE**: Most detailed information (e.g., function entry/exit)
+2. **DEBUG**: Diagnostic information useful during development
+3. **INFO**: General informational messages about app operation
+4. **WARN**: Warning messages for potentially problematic situations
+5. **ERROR**: Error messages for failures that don't stop the app
+
+## Automatic Console Forwarding
+
+The `attachConsole()` method automatically forwards all `console.*` calls to the plugin:
+
+```typescript
+await logger.initialize();
+
+// These are now logged to file AND console
+console.log("This is logged");      // → INFO level
+console.warn("Warning");             // → WARN level
+console.error("Error");              // → ERROR level
+```
+
+## File Rotation
+
+Logs automatically rotate when reaching 50KB size:
+
+- Current log: `debug.log`
+- Rotated logs: `debug.log.1`, `debug.log.2`, etc.
+- Old logs are preserved for historical analysis
+
+## Reading Logs
+
+### Via analyze_logs.sh Script
+
+```bash
+# Analyze logs with pattern detection
+./scripts/analyze_logs.sh
+
+# Custom log file path
+./scripts/analyze_logs.sh /path/to/debug.log
+```
+
+### Manual Reading
+
+```bash
+# macOS
+cat ~/Library/Logs/com.example.myapp/debug.log
+
+# Linux
+cat ~/.local/share/com.example.myapp/logs/debug.log
+
+# Windows (PowerShell)
+Get-Content $env:LOCALAPPDATA\com.example.myapp\logs\debug.log
+```
+
+## Troubleshooting
+
+### Logs Not Being Created
+
+1. **Check initialization**: Ensure `logger.initialize()` is called at app startup
+2. **Verify permissions**: `log:default` must be enabled in app capabilities
+3. **Check bundle ID**: Confirm correct bundle identifier in `tauri.conf.json`
+
+### Empty Log Files
+
+1. **No console output**: Call `logger.info()` or other methods to generate logs
+2. **Console not attached**: Verify `attachConsole()` was awaited successfully
+3. **Permission denied**: Check file system permissions for log directory
+
+### Cannot Find Log Files
+
+```bash
+# Use environment variable to locate logs
+echo $HOME/Library/Logs/{bundle_id}/debug.log  # macOS
+echo $HOME/.local/share/{bundle_id}/logs/debug.log  # Linux
+echo $env:LOCALAPPDATA\{bundle_id}\logs\debug.log  # Windows
+```
+
+## Advanced Usage
+
+### Custom Log Targets
+
+To modify logging targets, edit `src/lib.rs`:
+
+```rust
+use tauri_plugin_log::{Target, TargetKind};
+
+// Add custom target
+.targets([
+    Target::new(TargetKind::Stdout),
+    Target::new(TargetKind::LogDir {
+        file_name: Some("custom.log".to_string())
+    }),
+    // Add more targets as needed
+])
+```
+
+### Log Filtering
+
+Filter logs by level in Rust backend:
+
+```rust
+.level(log::LevelFilter::Debug)  // Only DEBUG and above
+```
+
+### Programmatic Log Access
+
+Access logs via filesystem APIs:
+
+```typescript
+import { readTextFile } from "@tauri-apps/plugin-fs";
+import { appLogDir } from "@tauri-apps/api/path";
+
+const logDir = await appLogDir();
+const logContent = await readTextFile(`${logDir}/debug.log`);
+```
+
+## Migration from Custom Logger
+
+See [MIGRATION.md](MIGRATION.md) for complete migration guide from `consoleLogger.ts`.
+
+## References
+
+- [Official tauri-plugin-log Documentation](https://v2.tauri.app/plugin/logging/)
+- [Rust log crate Documentation](https://docs.rs/log/latest/log/)
+- [analyze_logs.sh Script](../scripts/analyze_logs.sh)

package/skills/debug-tauri/references/MIGRATION.md

@@ -0,0 +1,487 @@
+# Migration Guide: Official Plugins Integration
+
+Complete guide for migrating from custom implementations to official Tauri plugins.
+
+## Overview
+
+This migration replaces:
+
+- **Custom `consoleLogger.ts`** → `tauri-plugin-log` (official)
+- **OS-dependent `screencapture` commands** → `tauri-plugin-screenshots`
+- **macOS-only support** → **Cross-platform** (macOS, Windows, Linux)
+
+## Migration Strategy
+
+### Recommended Approach: Parallel Deployment
+
+1. **Add official plugins alongside existing implementation**
+2. **Test in development environment**
+3. **Gradually switch to plugin APIs**
+4. **Remove custom implementation after validation**
+
+### Complete Migration Timeline
+
+- **v0.2.0**: Logging plugin added (parallel with consoleLogger)
+- **v0.3.0**: Screenshots plugin added
+- **v0.4.0**: Custom implementation removed
+- **v1.0.0**: Full cross-platform validation
+
+## Phase 1: Logging Migration
+
+### Before (Custom Implementation)
+
+```typescript
+// guest-js/consoleLogger.ts
+import { invoke } from "@tauri-apps/api/core";
+
+export async function appendDebugLogs(message: string): Promise<void> {
+  await invoke("plugin:debug-tools|append_debug_logs", { message });
+}
+
+export async function getConsoleLogs(): Promise<string[]> {
+  return await invoke("plugin:debug-tools|get_console_logs");
+}
+
+// Usage
+await appendDebugLogs("App started");
+const logs = await getConsoleLogs();
+```
+
+### After (Official Plugin)
+
+```typescript
+// guest-js/logAdapter.ts
+import { logger } from "tauri-plugin-debug-tools/logAdapter";
+
+// Initialize once at app startup
+const detach = await logger.initialize();
+
+// Usage
+logger.info("App started");
+
+// Logs automatically saved to platform-specific location
+// No need to manually retrieve logs
+```
+
+### Key Changes
+
+| Aspect | Custom | Official Plugin |
+|--------|---------|-----------------|
+| **Setup** | No initialization required | Requires `attachConsole()` call |
+| **Storage** | In-memory array | File-based with auto-rotation |
+| **Retrieval** | Manual `getConsoleLogs()` | Direct file access |
+| **Levels** | Single log level | trace/debug/info/warn/error |
+| **Persistence** | Lost on app restart | Persistent across restarts |
+| **Cross-platform** | No | Yes (macOS/Windows/Linux) |
+
+### Migration Steps
+
+#### 1. Add Dependencies
+
+**Cargo.toml**:
+
+```toml
+[dependencies]
+tauri-plugin-log = "2.0"
+```
+
+**package.json**:
+
+```json
+{
+  "dependencies": {
+    "@tauri-apps/plugin-log": "^2.0.0"
+  }
+}
+```
+
+#### 2. Initialize Plugin (src/lib.rs)
+
+```rust
+use tauri_plugin_log::{Target, TargetKind};
+
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    Builder::new("debug-tools")
+        .setup(|app, _api| {
+            app.handle().plugin(
+                tauri_plugin_log::Builder::new()
+                    .targets([
+                        Target::new(TargetKind::Stdout),
+                        Target::new(TargetKind::LogDir {
+                            file_name: Some("debug.log".to_string())
+                        }),
+                        Target::new(TargetKind::Webview),
+                    ])
+                    .max_file_size(50_000)
+                    .build()
+            )?;
+            Ok(())
+        })
+        .build()
+}
+```
+
+#### 3. Update Frontend Code
+
+**Replace**:
+
+```typescript
+import { appendDebugLogs } from "tauri-plugin-debug-tools/consoleLogger";
+await appendDebugLogs("Message");
+```
+
+**With**:
+
+```typescript
+import { logger } from "tauri-plugin-debug-tools/logAdapter";
+logger.info("Message");
+```
+
+#### 4. Update Permissions
+
+**Before** (`permissions/default.toml`):
+
+```toml
+permissions = [
+  "allow-append-debug-logs",
+  "allow-get-console-logs",
+]
+```
+
+**After** (`permissions/debug-with-logging.toml`):
+
+```toml
+permissions = [
+  "core:default",
+  "log:default",
+]
+```
+
+#### 5. Update Log Retrieval
+
+**Before**:
+
+```typescript
+const logs = await getConsoleLogs();
+console.log(logs.join("\n"));
+```
+
+**After**:
+
+```bash
+# Read from platform-specific location
+cat ~/Library/Logs/{bundle_id}/debug.log  # macOS
+```
+
+Or use `analyze_logs.sh` script:
+
+```bash
+./scripts/analyze_logs.sh
+```
+
+## Phase 2: Screenshot Migration
+
+### Before (macOS screencapture)
+
+```bash
+# scripts/capture.sh
+screencapture -x -T 0 "$output_path"
+```
+
+**Limitations**:
+
+- macOS only
+- Requires Screen Recording permission
+- Shell script dependency
+
+### After (Official Plugin)
+
+```typescript
+// guest-js/screenshotHelper.ts
+import { captureMainWindow } from "tauri-plugin-debug-tools/screenshotHelper";
+
+const imagePath = await captureMainWindow();
+// Returns base64 PNG data
+```
+
+**Benefits**:
+
+- Cross-platform (macOS/Windows/Linux)
+- No external dependencies
+- Programmatic access from TypeScript
+
+### Migration Steps
+
+#### 1. Add Dependencies
+
+**Cargo.toml**:
+
+```toml
+[dependencies]
+tauri-plugin-screenshots = "2.0"
+```
+
+**package.json**:
+
+```json
+{
+  "dependencies": {
+    "tauri-plugin-screenshots-api": "^2.0.0"
+  }
+}
+```
+
+#### 2. Initialize Plugin (src/lib.rs)
+
+```rust
+pub fn init<R: Runtime>() -> TauriPlugin<R> {
+    Builder::new("debug-tools")
+        .setup(|app, _api| {
+            app.handle().plugin(tauri_plugin_screenshots::init())?;
+            Ok(())
+        })
+        .build()
+}
+```
+
+#### 3. Update Frontend Code
+
+**Replace**:
+
+```bash
+TAURI_APP_NAME=myapp ./scripts/capture.sh
+```
+
+**With**:
+
+```typescript
+import { captureMainWindow } from "tauri-plugin-debug-tools/screenshotHelper";
+
+const screenshot = await captureMainWindow();
+if (screenshot) {
+  // screenshot is base64 PNG data
+  console.log("Screenshot captured");
+}
+```
+
+#### 4. Update Permissions
+
+Add to capabilities:
+
+```json
+{
+  "permissions": [
+    "screenshots:default"
+  ]
+}
+```
+
+## Common Migration Patterns
+
+### Pattern 1: App Initialization
+
+**Before**:
+
+```typescript
+// No special initialization
+```
+
+**After**:
+
+```typescript
+import { logger } from "tauri-plugin-debug-tools/logAdapter";
+
+async function initializeApp() {
+  const detach = await logger.initialize();
+
+  logger.info("App initialized");
+
+  // Store detach function for cleanup
+  window.addEventListener("beforeunload", () => detach());
+}
+```
+
+### Pattern 2: Error Logging
+
+**Before**:
+
+```typescript
+import { appendDebugLogs } from "./consoleLogger";
+
+try {
+  await riskyOperation();
+} catch (error) {
+  await appendDebugLogs(`Error: ${error.message}`);
+}
+```
+
+**After**:
+
+```typescript
+import { logger } from "tauri-plugin-debug-tools/logAdapter";
+
+try {
+  await riskyOperation();
+} catch (error) {
+  logger.error(`Error: ${error.message}`);
+}
+```
+
+### Pattern 3: Debug Snapshot
+
+**Before**:
+
+```typescript
+import { writeDebugSnapshot } from "./debugBridge";
+
+const logs = await getConsoleLogs();
+await writeDebugSnapshot({
+  timestamp: new Date().toISOString(),
+  logs,
+});
+```
+
+**After**:
+
+```typescript
+// Logs already persisted to file
+// Use writeDebugSnapshot for additional metadata only
+import { writeDebugSnapshot } from "./debugBridge";
+
+await writeDebugSnapshot({
+  timestamp: new Date().toISOString(),
+  // No need to include logs - already in debug.log
+});
+```
+
+## Rollback Strategy
+
+If migration causes issues, follow these steps:
+
+### 1. Keep Old Implementation
+
+Do not delete `consoleLogger.ts` until full validation:
+
+```typescript
+// Temporarily support both
+import { logger as newLogger } from "./logAdapter";
+import { appendDebugLogs as oldLogger } from "./consoleLogger";
+
+// Use feature flag
+const useOfficialPlugin = import.meta.env.VITE_USE_OFFICIAL_LOG === "true";
+
+export const logger = useOfficialPlugin ? newLogger : {
+  info: (msg) => oldLogger(msg),
+  error: (msg) => oldLogger(`ERROR: ${msg}`),
+  // ... other levels
+};
+```
+
+### 2. Gradual Feature Flag Rollout
+
+```typescript
+// Enable for specific environments
+const ENABLE_OFFICIAL_PLUGINS = {
+  development: true,
+  staging: true,
+  production: false, // Keep false until validated
+};
+
+const usePlugins = ENABLE_OFFICIAL_PLUGINS[import.meta.env.MODE];
+```
+
+### 3. Monitoring & Validation
+
+Before removing old implementation:
+
+- [ ] Verify logs appear in expected platform-specific locations
+- [ ] Confirm log rotation works (create 50KB+ logs)
+- [ ] Test screenshot capture on all target platforms
+- [ ] Validate permissions configuration
+- [ ] Check error handling for plugin initialization failures
+
+## Breaking Changes
+
+### Log Format
+
+**Before**: Plain strings in array
+
+```json
+["2024-01-01 12:00:00 - Message 1", "2024-01-01 12:00:01 - Message 2"]
+```
+
+**After**: Structured log lines in file
+
+```
+2024-01-01T12:00:00.123Z INFO  app_name: Message 1
+2024-01-01T12:00:01.456Z ERROR app_name: Message 2
+```
+
+### Log Access
+
+**Before**: Synchronous in-memory access
+
+```typescript
+const logs = await getConsoleLogs(); // Returns immediately
+```
+
+**After**: File system access required
+
+```typescript
+// Read from filesystem
+import { readTextFile } from "@tauri-apps/plugin-fs";
+import { appLogDir } from "@tauri-apps/api/path";
+
+const logDir = await appLogDir();
+const logs = await readTextFile(`${logDir}/debug.log`);
+```
+
+## Platform-Specific Considerations
+
+### macOS
+
+- **Log Location**: `~/Library/Logs/{bundle_id}/debug.log`
+- **Permissions**: No special permissions required for logging
+- **Screenshots**: Works without Screen Recording permission (captures own windows)
+
+### Windows
+
+- **Log Location**: `%LOCALAPPDATA%\{bundle_id}\logs\debug.log`
+- **Permissions**: Standard file write permissions
+- **Screenshots**: Works with standard permissions
+
+### Linux
+
+- **Log Location**: `~/.local/share/{bundle_id}/logs/debug.log`
+- **Permissions**: Standard file write permissions
+- **Screenshots**: May require Wayland/X11 specific permissions
+
+## Validation Checklist
+
+Before marking migration complete:
+
+- [ ] Official plugins added to Cargo.toml and package.json
+- [ ] Plugins initialized in src/lib.rs
+- [ ] Permissions updated in capabilities
+- [ ] Frontend code updated to use new APIs
+- [ ] Log files created in correct platform-specific locations
+- [ ] Log rotation tested (50KB threshold)
+- [ ] Screenshots work on all target platforms
+- [ ] Error handling tested (plugin init failures)
+- [ ] Documentation updated
+- [ ] Old implementation removed (or feature-flagged)
+
+## Support
+
+For migration issues:
+
+1. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common problems
+2. Review [LOGGING.md](LOGGING.md) for plugin configuration details
+3. See [SCREENSHOTS.md](SCREENSHOTS.md) for screenshot API usage
+4. Open issue on GitHub repository with migration context
+
+## References
+
+- [tauri-plugin-log Documentation](https://v2.tauri.app/plugin/logging/)
+- [tauri-plugin-screenshots Repository](https://github.com/ayangweb/tauri-plugin-screenshots)
+- [Migration Plan](../../../../.claude/plans/shiny-knitting-squirrel.md)