tauri-plugin-debug-tools 0.1.0

package/AGENTS.md

@@ -0,0 +1,346 @@
+# Agent Development Guide
+
+> Guidance for AI agents working with tauri-plugin-debug-tools
+
+## Project Overview
+
+**tauri-plugin-debug-tools** is a Tauri plugin that provides comprehensive debugging utilities for WebView applications. It combines a Rust backend (Tauri plugin) with a TypeScript frontend (log collection and state inspection) and includes an AI-powered debugging skill for AI agents.
+
+## Architecture
+
+### Components
+
+```
+tauri-plugin-debug-tools/
+├── src/                          # Rust backend (Tauri plugin)
+│   ├── lib.rs                    # Plugin initialization
+│   └── commands.rs               # Tauri command implementations
+├── guest-js/                     # TypeScript frontend
+│   ├── consoleLogger.ts          # Log collection system
+│   ├── debugBridge.ts            # Backend IPC bridge
+│   └── index.ts                  # Public exports
+├── skills/debug-tauri/           #  Agent Skill
+│   ├── SKILL.md                  # Skill definition
+│   ├── references/REFERENCE.md   # Technical reference
+│   └── scripts/capture.sh        # Screenshot helper script
+├── permissions/                  # Tauri permission schemas
+├── build.rs                      # Build script
+├── Cargo.toml                    # Rust dependencies
+├── package.json                  # TypeScript dependencies
+└── tsconfig.json                 # TypeScript configuration
+```
+
+### Key Technologies
+
+- **Rust**: Tauri plugin backend (edition 2021)
+- **TypeScript**: Frontend utilities (v5.0+)
+- **Tauri**: v2.9.5
+- **Bun**: Package manager & runtime
+- **Biome**: Linting & formatting
+
+## Design Patterns
+
+### 1. Ring Buffer Log Collection
+
+[guest-js/consoleLogger.ts](guest-js/consoleLogger.ts) implements a sophisticated logging system:
+
+- **Ring Buffer**: Max 1,000 entries, auto-drops oldest
+- **Batched Flushing**: Every 1s or 200 pending logs
+- **Global Error Handling**: Captures `error` and `unhandledrejection` events
+- **Stack Trace Normalization**: Filters internal frames
+- **Zero Dependencies**: No Safari DevTools required
+
+**Key Design Decision**: Logs are collected in-memory on the frontend and periodically flushed to the system temp directory (for example, `/tmp/tauri_console_logs.jsonl`) via Tauri IPC. This avoids blocking the main thread and provides resilience against IPC failures.
+
+### 2. Event-Based Debug Commands
+
+Debug commands use Tauri's event system for safe, CSP-compliant communication:
+
+```rust
+// src/commands.rs
+window.emit("debug-command", (command, payload))
+```
+
+This approach:
+
+- Preserves Content Security Policy compliance
+- Avoids dynamic code execution
+- Allows frontend handlers to process commands safely
+
+### 3. System Command Integration
+
+Screenshot functionality delegates to system commands (e.g., macOS `screencapture`) rather than implementing platform-specific capture logic. This reduces dependencies and leverages battle-tested tools.
+
+## Common Tasks
+
+### Adding a New Tauri Command
+
+1. **Define the command** in [src/commands.rs](src/commands.rs):
+
+```rust
+#[tauri::command]
+pub async fn my_new_command<R: Runtime>(
+    app: AppHandle<R>,
+    param: String,
+) -> Result<String, String> {
+    // Implementation
+    Ok("success".to_string())
+}
+```
+
+1. **Register the command** in [src/lib.rs](src/lib.rs):
+
+```rust
+.invoke_handler(tauri::generate_handler![
+    // ... existing commands
+    commands::my_new_command,
+])
+```
+
+1. **Add to build script** in [build.rs](build.rs):
+
+```rust
+const COMMANDS: &[&str] = &[
+    // ... existing commands
+    "my_new_command",
+];
+```
+
+1. **Create TypeScript wrapper** in [guest-js/debugBridge.ts](guest-js/debugBridge.ts):
+
+```typescript
+export async function myNewCommand(param: string): Promise<string> {
+    return await invoke<string>("plugin:debug-tools|my_new_command", { param });
+}
+```
+
+1. **Update exports** in [guest-js/index.ts](guest-js/index.ts) if needed.
+
+### Extending Console Logger
+
+To add custom log processing:
+
+1. **Modify [guest-js/consoleLogger.ts](guest-js/consoleLogger.ts)**:
+
+```typescript
+class ConsoleLogCollector {
+    // Add new method
+    public filterByPattern(pattern: RegExp): ConsoleLogEntry[] {
+        return this.logs.filter(log => pattern.test(log.message));
+    }
+}
+
+// Export at bottom
+export const filterLogsByPattern = (pattern: RegExp) =>
+    consoleLogger.filterByPattern(pattern);
+```
+
+1. **Update TypeScript types** if adding new log properties.
+
+### Modifying the Agent Skill
+
+The skill is defined in [skills/debug-tauri/SKILL.md](skills/debug-tauri/SKILL.md):
+
+- **Frontmatter**: Contains skill metadata (name, description)
+- **Workflow Section**: Defines the debugging process
+- **Debug Report Template**: Standardizes output format
+
+When updating the skill:
+
+1. Modify the workflow steps to match new capabilities
+2. Update the debug report template if new data is collected
+3. Update [skills/debug-tauri/references/REFERENCE.md](skills/debug-tauri/references/REFERENCE.md) with new command documentation
+
+## Development Workflow
+
+### Building
+
+```bash
+# Install dependencies
+bun install
+
+# Build TypeScript
+npm run build
+
+# This generates:
+# - dist/index.js & dist/index.d.ts
+# - dist/consoleLogger.js & dist/consoleLogger.d.ts
+# - dist/debugBridge.js & dist/debugBridge.d.ts
+```
+
+### Linting & Formatting
+
+```bash
+# Run all linters
+npm run lint
+
+# Check Biome rules
+npm run lint:biome
+
+# Check TypeScript types
+npm run lint:tsc
+
+# Auto-fix issues
+npm run format
+```
+
+### Testing the Plugin
+
+Since this is a Tauri plugin, testing requires a host Tauri application:
+
+1. Create a test Tauri app or use an existing one
+2. Add the plugin as a dependency:
+
+   ```toml
+   [dependencies]
+   tauri-plugin-debug-tools = { path = "../tauri-plugin-debug-tools" }
+   ```
+
+3. Register the plugin and enable permissions
+4. Run `tauri dev` and test IPC commands
+
+## Important Constraints
+
+### Platform-Specific Code
+
+- **Log File Paths**: Currently hardcoded to `/tmp/` (Unix-like systems only)
+- **Screenshot**: Uses macOS `screencapture` command
+- **User-Agent**: Hardcoded to `"TauriWebView/2.0"` (TODO: fetch real UA)
+
+For cross-platform support:
+
+```rust
+// Use this instead of "/tmp/"
+let temp_dir = std::env::temp_dir();
+let log_path = temp_dir.join("tauri_console_logs.jsonl");
+```
+
+### Performance Considerations
+
+- **Log Buffer Size**: Limited to 1,000 entries to prevent memory bloat
+- **Batch Size**: Max 200 logs per flush to avoid blocking IPC
+- **Screenshot**: Delegated to system command (no in-process capture)
+
+### Security Considerations
+
+- **Event-Based Communication**: All commands use Tauri events (no dynamic code execution)
+- **CSP Compliant**: No inline scripts or unsafe constructs
+- **Sandboxed**: Tauri security model enforced
+- **Log Sanitization**: Stack traces are normalized to remove sensitive paths
+
+## Code Style
+
+### Rust
+
+- **Edition**: 2021
+- **Style**: Standard Rust formatting (`rustfmt`)
+- **Error Handling**: Return `Result<T, String>` from commands
+- **Async**: Use `async fn` for all commands
+
+### TypeScript
+
+- **Target**: ES2020+ (module)
+- **Strict Mode**: Enabled
+- **Formatting**: Biome (configured in [package.json](package.json))
+- **Naming**:
+  - Functions: `camelCase`
+  - Types/Interfaces: `PascalCase`
+  - Constants: `UPPER_SNAKE_CASE` (if truly constant)
+
+### Documentation
+
+- **README**: Comprehensive user guide with examples
+- **AGENTS.md**: This file - agent development guide
+- **SKILL.md**: Skill definition in YAML frontmatter + Markdown body
+- **REFERENCE.md**: Technical reference for IPC commands
+- **Inline Comments**: Explain "why", not "what"
+
+## Testing Strategy
+
+### Manual Testing Checklist
+
+When making changes, verify:
+
+- [ ] TypeScript builds without errors (`npm run build`)
+- [ ] All linters pass (`npm run lint`)
+- [ ] Plugin registers in host app without errors
+- [ ] IPC commands return expected results
+- [ ] Console logger captures logs correctly
+- [ ] Logs flush to system temp dir (for example, `/tmp/tauri_console_logs.jsonl`)
+- [ ] Agent skill can be invoked (`/debug-tauri`)
+- [ ] Screenshot capture works (macOS)
+
+### Future: Automated Testing
+
+Consider adding:
+
+- Unit tests for TypeScript utilities (`vitest`)
+- Integration tests for Tauri commands (`tauri-driver`)
+- E2E tests for the agent skill
+
+## Common Pitfalls
+
+### 1. Window Label Mismatch
+
+The plugin assumes the main window is labeled `"main"`. If your app uses a different label:
+
+```rust
+// src/commands.rs - update this
+let window = app.get_webview_window("main") // Change to your label
+```
+
+### 2. Permission Not Enabled
+
+Users must add `"debug-tools:default"` to their app's capabilities. If commands fail with permission errors, this is likely the cause.
+
+### 3. Tauri Ready Event Timing
+
+The console logger waits for `window.__TAURI__` or `tauri://ready` event before flushing logs. If logs aren't being saved, check that:
+
+- Tauri API is loaded before the logger
+- No JavaScript errors prevent the event from firing
+
+### 4. TypeScript Build Not Included
+
+Remember to run `npm run build` before publishing or testing. The `dist/` folder is what gets imported by users.
+
+## Release Checklist
+
+Before releasing a new version:
+
+1. [ ] Update version in [Cargo.toml](Cargo.toml) and [package.json](package.json)
+2. [ ] Update [README.md](README.md) with new features
+3. [ ] Run `npm run build` and commit `dist/`
+4. [ ] Run `npm run lint` (all checks must pass)
+5. [ ] Test with a real Tauri app
+6. [ ] Update [skills/debug-tauri/SKILL.md](skills/debug-tauri/SKILL.md) if workflow changed
+7. [ ] Tag release: `git tag v0.x.0`
+8. [ ] Push tag: `git push origin v0.x.0`
+
+## Resources
+
+### Official Documentation
+
+- [Tauri Plugin Development](https://tauri.app/develop/plugins/)
+- [Tauri IPC Guide](https://v2.tauri.app/develop/calling-rust/)
+- [Claude Code Skills](https://code.claude.com/docs/skills)
+
+### Internal References
+
+- [Technical Reference](skills/debug-tauri/references/REFERENCE.md) - IPC command details
+- [Skill Definition](skills/debug-tauri/SKILL.md) - Agent workflow
+- [README](README.md) - User documentation
+
+## Support
+
+For questions or issues:
+
+- GitHub Issues: (repository URL)
+- Discord: (community link)
+- Email: (maintainer email)
+
+---
+
+**Last Updated**: 2025-12-31
+**Version**: 0.1.0
+**Maintainer**: (your name/team)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 sadao komaki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,303 @@
+# tauri-plugin-debug-tools
+
+Comprehensive debug utilities for Tauri WebView applications with AI-powered automated debugging workflows.
+
+## Features
+
+- **WebView State Capture** - Capture URL, title, viewport, and User-Agent
+- **Console Log Collection** - Ring-buffer based log collection with batched flushing
+- **Screenshot Integration** - System screenshot command integration
+- **AI Agent Skill** - Automated debugging workflow for AI agents
+- **Debug Snapshots** - Save comprehensive debug state to disk
+- **Event-based Communication** - Send debug commands to frontend via Tauri events
+
+## Quick Start
+
+### Installation
+
+Add to your Tauri project's `Cargo.toml`:
+
+```toml
+[dependencies]
+tauri-plugin-debug-tools = "0.1.0"
+```
+
+Install the frontend package:
+
+```bash
+npm install tauri-plugin-debug-tools
+# or
+bun add tauri-plugin-debug-tools
+```
+
+### Setup
+
+**1. Register the plugin** in your Tauri app:
+
+```rust
+// src-tauri/src/main.rs or lib.rs
+fn main() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_debug_tools::init())
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+**2. Configure the plugin (optional)** in your `tauri.conf.json` if you want to override defaults:
+
+```json
+{
+    "plugins": {
+        "debug-tools": {
+            "timeout": 30
+        }
+    }
+}
+```
+
+If you don't need custom configuration, you can omit this section.
+
+**3. Enable permissions** in `src-tauri/capabilities/default.json`:
+
+```json
+{
+  "permissions": [
+    "debug-tools:default"
+  ]
+}
+```
+
+    **4. Initialize frontend logger** in your app entry point:
+
+```typescript
+// src/main.ts or src/App.tsx
+import { debugTools } from "tauri-plugin-debug-tools/consoleLogger";
+
+// Use instead of console.*
+debugTools.log("Application started");
+debugTools.error("Something went wrong");
+
+// Or import individual functions
+import { log, error, warn } from "tauri-plugin-debug-tools/consoleLogger";
+```
+
+## Usage
+
+### Frontend API
+
+#### Console Logging
+
+```typescript
+import { debugTools, consoleLogger } from "tauri-plugin-debug-tools/consoleLogger";
+
+// Log messages (automatically collected)
+debugTools.log("Info message");
+debugTools.warn("Warning message");
+debugTools.error("Error message", { context: "data" });
+
+// Retrieve logs
+const allLogs = consoleLogger.getLogs();
+const errors = consoleLogger.getErrors();
+const recent = consoleLogger.getRecentLogs(50);
+
+// Get statistics
+const stats = consoleLogger.getStats();
+// { total: 150, byLevel: { log: 100, warn: 30, error: 20, info: 0, debug: 0 } }
+```
+
+#### WebView State Inspection
+
+```typescript
+import { captureWebViewState } from "tauri-plugin-debug-tools/debugBridge";
+
+const state = await captureWebViewState();
+console.log(state);
+// {
+//   url: "http://localhost:5173",
+//   title: "My App",
+//   user_agent: "TauriWebView/2.0",
+//   viewport: { width: 1200, height: 800 }
+// }
+```
+
+#### Debug Commands
+
+```typescript
+import { sendDebugCommand } from "tauri-plugin-debug-tools/debugBridge";
+
+// Send event-based commands to frontend
+await sendDebugCommand("refresh_state", { force: true });
+```
+
+### Backend Commands
+
+All commands are available through the Tauri IPC system:
+
+| Command | Description | Output |
+| ------- | ----------- | ------ |
+| `capture_webview_state` | Capture WebView state | `WebViewState` JSON |
+| `get_console_logs` | Legacy console logs | Empty array (use frontend logger) |
+| `send_debug_command` | Send event to frontend | Success message |
+| `append_debug_logs` | Append logs to file | System temp dir (e.g., `/tmp/tauri_console_logs.jsonl`) |
+| `reset_debug_logs` | Clear log file | File path |
+| `write_debug_snapshot` | Save debug snapshot | System temp dir (e.g., `/tmp/tauri_debug_snapshot_*.json`) |
+
+## AI Agent Skill
+
+### Skill Installation
+
+Copy the bundled skill to your agent's skills directory:
+
+(example: Codex)
+
+```bash
+cp -R skills/debug-tauri ~/.codex/skills/debug-tauri
+```
+
+Or for custom skill directories:
+
+```bash
+cp -R skills/debug-tauri /path/to/your/skills/debug-tauri
+```
+
+### Skill Usage
+
+Invoke the skill to start automated debugging:
+
+```bash
+/debug-tauri
+```
+
+The skill will:
+
+1. ✅ Verify the app process is running
+2. 📸 Capture a screenshot
+3. 📝 Collect console logs (via IPC)
+4. 🔍 Analyze visual and runtime state
+5. 📄 Generate a comprehensive debug report
+6. 💡 Propose fixes based on findings
+
+### Example Report
+
+```markdown
+# Tauri Debug Report - 2025-12-31T22:00:00Z
+
+## Screenshot
+/tmp/tauri_debug_1735689600.png
+
+## Process Status
+- Status: Running
+- PID: 12345
+
+## Console Logs
+### Recent Errors
+- [ERROR] WebGL context lost (timestamp: 1735689550)
+- [ERROR] Failed to load texture.png (timestamp: 1735689555)
+
+### Log Statistics
+- Total: 1,234 logs
+- Errors: 2
+- Warnings: 15
+
+## Visual Analysis
+### UI State
+Main window visible with rendering artifacts in canvas area.
+
+### Recommendations
+1. Investigate WebGL context loss - check GPU driver
+2. Verify texture.png exists in public/ directory
+```
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph DevEnv["Development Environment"]
+        subgraph AIAgent["AI Agent (Codex/Claude Code)"]
+            Skill["debug-tauri skill<br/>- Process verification<br/>- Screenshot capture<br/>- Log collection<br/>- Analysis & reporting"]
+        end
+
+        subgraph Tauri["Tauri Application"]
+            subgraph Frontend["Frontend (TypeScript)"]
+                CL["consoleLogger<br/>- Ring buffer (1000 entries)<br/>- Auto flush (1s/200 logs)<br/>- Error handling"]
+                DB["debugBridge<br/>- State capture<br/>- Log retrieval<br/>- Debug commands"]
+                CL -->|"Logs"| DB
+            end
+
+            subgraph Backend["Backend (Rust)"]
+                Plugin["tauri-plugin-debug-tools<br/>- capture_webview_state<br/>- append_debug_logs<br/>- reset_debug_logs<br/>- write_debug_snapshot<br/>- send_debug_command"]
+            end
+
+            DB -->|"Tauri IPC"| Plugin
+            CL -->|"Batch flush"| Plugin
+        end
+
+        FS["File System<br/>Temp dir (logs & snapshots)<br/>e.g., /tmp/tauri_console_logs.jsonl"]
+
+        Plugin -->|"Write logs & snapshots"| FS
+    end
+
+    Skill -->|"1. Verify process"| Tauri
+    Skill -->|"2. Invoke IPC commands"| DB
+    Skill -->|"3. Read logs & snapshots"| FS
+    Skill -->|"4. Capture screenshot"| FS
+    FS -->|"5. Analyze & report"| Skill
+
+    style Frontend fill:#e1f5ff
+    style Backend fill:#ffe1e1
+    style FS fill:#fff4e1
+    style AIAgent fill:#f0e1ff
+    style Skill fill:#e8d4ff
+```
+
+## Log Collection System
+
+The plugin uses a sophisticated ring-buffer based logging system:
+
+- **Buffer Size**: Max 1,000 log entries (automatically drops oldest)
+- **Batch Flushing**: Every 1 second or 200 pending logs
+- **Auto-initialization**: Starts on module load
+- **Error Handling**: Catches global `error` and `unhandledrejection` events
+- **Stack Traces**: Automatically captures and normalizes stack traces
+- **Zero Config**: No Safari DevTools required
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build TypeScript
+npm run build
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+```
+
+## Platform Support
+
+- ✅ macOS (tested)
+- ⚠️ Windows (uses system temp directory for logs/snapshots)
+- ⚠️ Linux (uses system temp directory for logs/snapshots)
+
+## License
+
+This project is licensed under either of:
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Related Projects
+
+- [Tauri](https://tauri.app) - Build smaller, faster, and more secure desktop applications
+- [Codex](https://github.com/anthropics/anthropic-sdk-typescript) - AI-powered code assistant