Initial commit: PlugSnatcher basic structure

This commit is contained in:
Rbanh committed 2025-03-29 00:52:17 -04:00
commit d9cf404402
46 files changed
+10036

No files matched your search

+202
View File
@@ -0,0 +1,202 @@
---
description: Outlines the technical architecture of the PlugSnatcher application, providing an overview of the system design, component interactions, and data flow.
globs:
alwaysApply: false
---
## System Overview
PlugSnatcher is a desktop application built using Tauri, combining a Rust backend with a React/TypeScript frontend:
- **Frontend**: React + TypeScript for the user interface
- **Backend**: Rust for file system operations and plugin analysis
- **Bridge**: Tauri for integration between frontend and backend
## Architecture Diagram
```
+------------------------------------+ +------------------------------------+
| FRONTEND | | BACKEND |
| (React + TypeScript) | | (Rust) |
| | | |
| +----------------------------+ | | +----------------------------+ |
| | Components | | | | Core Functions | |
| | | | | | | |
| | - App.tsx | | | | - Plugin Scanner | |
| | - ServerInfoDisplay | | | | - Metadata Extractor | |
| | - PluginDetails |<---|------|->| - Server Type Detector | |
| | | | | | - Hash Calculator | |
| +----------------------------+ | | +----------------------------+ |
| | | |
| +----------------------------+ | | +----------------------------+ |
| | State Management | | | | Data Models | |
| | | | | | | |
| | - useState Hooks | | | | - Plugin | |
| | - Future Context API |<---|------|->| - ServerInfo | |
| | | | | | - PluginMeta | |
| +----------------------------+ | | +----------------------------+ |
| | | |
+------------------------------------+ +------------------------------------+
^ ^
| |
| Tauri Bridge |
| |
v v
+------------------------------------+ +------------------------------------+
| EXTERNAL SERVICES | | FILESYSTEM ACCESS |
| | | |
| - Web Crawler | | - Server Directory |
| - Plugin Repositories API | | - Plugin JAR Files |
| - Update Detection | | - Configuration Files |
| | | |
+------------------------------------+ +------------------------------------+
```
## Component Breakdown
### Frontend (React + TypeScript)
1. **Main Components**:
- `App`: The main application component that orchestrates the UI
- `ServerInfoDisplay`: Displays information about the Minecraft server
- `PluginDetails`: Shows detailed information about a selected plugin
2. **State Management**:
- Currently uses React's `useState` for local component state
- Future: May implement Context API for global state as app complexity grows
3. **Frontend Services**:
- Tauri invoke calls to the Rust backend
- UI state management
- Event handling
- Future: Web service integration
### Backend (Rust)
1. **Core Modules**:
- `Plugin Scanner`: Scans directories for plugin JAR files
- `Metadata Extractor`: Extracts plugin.yml data from JAR files
- `Server Type Detector`: Identifies the Minecraft server type
- `Hash Calculator`: Generates SHA-256 hashes for plugin files
2. **Data Models**:
- `Plugin`: Represents a Minecraft plugin with its metadata
- `ServerInfo`: Contains information about the server type and configuration
- `PluginMeta`: Raw metadata extracted from plugin files
- `ScanResult`: Combined result of a server scan operation
3. **Command API**:
- `scan_server_directory`: Scans a server for plugins and server information
- Future: Commands for update checking, plugin installation, etc.
## Data Flow
1. **User Initiates Server Scan**:
```
UI Action -> Frontend Event Handler -> Tauri Invoke -> Rust Command ->
Filesystem Access -> Plugin Analysis -> Result Serialization ->
Frontend State Update -> UI Rendering
```
2. **Plugin Detail View**:
```
Plugin Selection -> State Update -> UI Component Rendering
```
3. **Future: Plugin Update Process**:
```
Update Check -> Web API Call -> Compare Versions ->
UI Notification -> User Confirmation -> Download ->
Backup Original -> Replace Plugin -> Refresh UI
```
## Database/Storage
Current implementation uses in-memory state with no persistence. Future versions will implement:
1. **Local Storage Options**:
- SQLite database for plugin metadata and scan history
- JSON file storage for configuration and preferences
- Filesystem for plugin backups
2. **Data Schema** (Planned):
```
Servers
- ServerID
- ServerPath
- ServerType
- LastScan
Plugins
- PluginID
- ServerID (FK)
- Name
- Version
- FilePath
- FileHash
- LastUpdated
Updates
- UpdateID
- PluginID (FK)
- AvailableVersion
- ReleaseDate
- ChangelogURL
```
## Security Considerations
1. **File System Access**:
- Limited to reading plugin directories and JAR files
- No modification of server files without explicit permission
2. **Network Security** (Future):
- Verification of downloaded plugins via checksums
- HTTPS for all external API communications
- Sandboxed plugin downloads
3. **Error Handling**:
- Graceful error recovery
- User-friendly error messages
- Detailed error logging
## Scalability Considerations
1. **Performance Optimizations**:
- Asynchronous plugin scanning for large server directories
- Caching of plugin metadata to reduce repeated JAR parsing
- Incremental updates of the plugin list
2. **Modularity**:
- Design for extensibility with new features
- Clear separation between UI and business logic
- Modular crawler system for multiple plugin sources
## Future Architecture Extensions
1. **Plugin Update System**:
- Web crawler for multiple plugin repositories
- Version comparison engine
- Plugin download and installation manager
2. **Server Management**:
- Multiple server profile support
- Server start/stop controls
- Configuration file editing
3. **Enhanced UI**:
- Dashboard with server health metrics
- Plugin conflict detection
- Compatibility matrix
## Development Environment
- **Frontend**: Node.js, npm, TypeScript, React
- **Backend**: Rust, Cargo
- **Build System**: Tauri CLI
- **Deployment**: Self-contained executables for Windows (primary), potentially macOS and Linux
## Conclusion
This architecture provides a solid foundation for the PlugSnatcher application while allowing for scalability and future enhancements. The separation of concerns between the frontend and backend ensures that each part can evolve independently while maintaining a coherent system.
As the application grows, this document should be updated to reflect architectural changes and new components.
+10
View File
@@ -0,0 +1,10 @@
---
description:
globs:
alwaysApply: true
---
# Your rule content
- You can @ files here
- You can use markdown but dont have to
+173
View File
@@ -0,0 +1,173 @@
---
description:
globs:
alwaysApply: true
---
# PlugSnatcher Development Workflow
This document outlines the development workflow and best practices for the PlugSnatcher application. Following these guidelines will help maintain consistency and scalability as the project grows.
## Project Architecture
PlugSnatcher is a desktop application built with:
- **Frontend**: React + TypeScript
- **Backend**: Rust + Tauri
- **Data Handling**: In-memory state, potential future SQLite/JSON storage
### Project Structure
```
PlugSnatcher/
├── src/ # Frontend code (React + TypeScript)
│ ├── App.tsx # Main application component
│ ├── App.css # Application styles
│ └── assets/ # Static assets
├── src-tauri/ # Backend code (Rust)
│ ├── src/ # Rust source code
│ │ ├── lib.rs # Core backend functionality
│ │ └── main.rs # Tauri application entry point
│ ├── Cargo.toml # Rust dependencies
│ ├── tauri.conf.json # Tauri configuration
│ └── capabilities/ # Tauri v2 capabilities configs
├── public/ # Public static files
└── ROADMAP.md # Project roadmap and progress tracking
```
## Development Workflow
### 1. Feature Planning
1. **Consult Roadmap**: Check the `ROADMAP.md` file to identify the next feature to implement
2. **Define Scope**: Clearly define what the feature will do and identify any dependencies
3. **Update Roadmap**: Mark features as "In Progress" when starting work
### 2. Implementation Process
For each new feature, follow this general workflow:
#### Backend (Rust) Development
1. **Define Data Models**: Create necessary structs and enums in `lib.rs`
2. **Implement Core Logic**: Develop the backend functionality in Rust
3. **Create Tauri Commands**: Expose functionality to the frontend through command annotations
4. **Update Dependencies**: Add any new dependencies to `Cargo.toml`
5. **Configure Permissions**: Update capability files if new permissions are needed
#### Frontend (React) Development
1. **Define Interfaces**: Create TypeScript interfaces that match Rust structs
2. **Implement UI Components**: Create or update React components
3. **Connect to Backend**: Use Tauri's invoke to call Rust functions
4. **Style Components**: Update CSS for new UI elements
5. **Handle Edge Cases**: Ensure proper error handling and loading states
### 3. Testing
- **Manual Testing**: Test features thoroughly on Windows (primary platform)
- **Edge Cases**: Test with various plugin formats and server setups
- **Error Handling**: Verify all error paths work correctly
### 4. Documentation
- **Update Roadmap**: Mark completed features
- **Code Documentation**: Add comments for complex logic
- **User Documentation**: Update usage instructions if needed
## Code Conventions
### Rust Conventions
1. **Error Handling**:
- Use `Result<T, String>` for functions that may fail
- Provide descriptive error messages
- Use the `?` operator with `.map_err()` for context
2. **Struct Definitions**:
- Include `#[derive]` attributes for serialization
- Organize fields logically
- Use proper visibility modifiers (pub when needed)
3. **Function Organization**:
- Group related functions together
- Extract helper functions for reusable logic
- Add documentation comments for public functions
### TypeScript/React Conventions
1. **Component Structure**:
- Use functional components with hooks
- Define props interfaces for all components
- Keep components focused on a single responsibility
2. **State Management**:
- Use React's `useState` for local state
- Use `useContext` if state needs to be shared
- Consider state management libraries for complex state (future enhancement)
3. **Styling Approach**:
- Use CSS variables for theming
- Organize CSS by component hierarchy
- Use consistent naming conventions
## Scalability Considerations
### Performance Optimization
1. **Large Plugin Collections**:
- Implement pagination or virtualization for long lists
- Optimize file scanning operations
- Consider background processing for intensive operations
2. **Memory Management**:
- Be mindful of memory usage with large JAR files
- Release resources properly after use
### Future Extensions
1. **Plugin Architecture**:
- Design the crawler system with flexibility for multiple sources
- Use interfaces and traits for different plugin repository types
2. **Database Integration**:
- Prepare for potential migration to a database for persistent storage
- Design data models with this in mind
3. **Multi-Server Management**:
- Consider how the architecture might expand to handle multiple servers
## Troubleshooting Common Issues
### Rust/Tauri Issues
1. **Permission Errors**:
- Check Tauri capability files in `capabilities/` directory
- Ensure proper permissions are granted for each plugin
2. **Build Errors**:
- Verify Rust dependencies in `Cargo.toml`
- Check for incompatible versions
### TypeScript/React Issues
1. **Type Errors**:
- Ensure TypeScript interfaces match Rust structs
- Use proper type assertions for nullable values
2. **UI Rendering Issues**:
- Check CSS specificity and hierarchy
- Verify conditional rendering logic
## Deployment Process
1. **Version Bump**:
- Update version in `package.json` and `Cargo.toml`
2. **Build Process**:
- Run `npm run tauri build` for production builds
- Test the packaged application before distribution
3. **Distribution**:
- Package for Windows (primary platform)
- Consider multi-platform support as needed
## Conclusion
By following this workflow, the PlugSnatcher project will maintain a consistent structure and approach as it scales. This document should be updated as the project evolves to reflect any changes in best practices or architecture.
+192
View File
@@ -0,0 +1,192 @@
---
description:
globs:
alwaysApply: true
---
# Git Workflow for PlugSnatcher
This document outlines the Git workflow for PlugSnatcher development to maintain code quality and enable collaboration.
## Initial Setup
If you haven't already set up Git for the project:
```bash
# Initialize git repository
git init
# Add all current files
git add .
# Make the initial commit
git commit -m "Initial commit: PlugSnatcher basic structure"
# Create a remote repository on GitHub (if not already done)
# Then connect your local repository
git remote add origin https://git.spacetrainclubhouse.com/Space-Train-Clubhouse/PlugSnatcher.git
git push -u origin main
```
## Branch Structure
Maintain a structured branching strategy:
- `main`: Production-ready code
- `develop`: Main development branch
- Feature branches: `feature/feature-name`
- Bug fix branches: `fix/bug-description`
## Feature Development Workflow
1. **Create a Feature Branch**
Always branch from `develop` for new features:
```bash
git checkout develop
git pull
git checkout -b feature/plugin-scanner
```
2. **Make Regular Commits**
Commit changes with descriptive messages:
```bash
git add .
git commit -m "Add plugin metadata extraction functionality"
```
3. **Merge Back to Develop**
When the feature is complete:
```bash
git checkout develop
git pull
git merge feature/plugin-scanner
git push
```
## Bug Fix Workflow
1. **Create a Bug Fix Branch**
```bash
git checkout develop
git pull
git checkout -b fix/plugin-metadata-error
```
2. **Fix and Test**
Make the necessary changes and test thoroughly.
3. **Commit and Merge**
```bash
git add .
git commit -m "Fix plugin metadata extraction for malformed YML files"
git checkout develop
git pull
git merge fix/plugin-metadata-error
git push
```
## Versioning
Use semantic versioning (MAJOR.MINOR.PATCH):
- **MAJOR**: Incompatible API changes
- **MINOR**: New functionality in a backward-compatible manner
- **PATCH**: Backward-compatible bug fixes
When releasing a new version:
```bash
# Tag the release
git tag -a v0.1.0 -m "Initial beta release with plugin scanning"
git push origin v0.1.0
```
## Commit Message Guidelines
Write clear, concise commit messages following these guidelines:
- Use present tense ("Add feature" not "Added feature")
- Start with a verb
- Keep the first line under 50 characters
- Reference issues or tickets where applicable
- Include details in commit body if needed
Examples:
- "Add server type detection for Paper and Spigot"
- "Fix permission error in dialog plugin initialization"
- "Improve UI layout for plugin details modal"
## Pull Request Process
When working in a team:
1. Push your branch to GitHub
2. Create a Pull Request (PR) to the `develop` branch
3. Request code review from at least one team member
4. Address any comments or feedback
5. Merge PR once approved
## Git Best Practices for PlugSnatcher
1. **Handle Large Binary Files Properly**
Avoid committing large JAR files or test plugins to the repository. Use `.gitignore` to exclude these files.
2. **Handle Sensitive Information**
Never commit API keys, credentials, or sensitive configuration files. Use environment variables or configuration templates.
3. **Regular Backups**
Regularly push to the remote repository to maintain backups of your work.
## Git Ignore Configuration
Ensure your `.gitignore` file contains the following patterns:
```
# Node dependencies
node_modules/
npm-debug.log
yarn-debug.log
yarn-error.log
# Rust build artifacts
target/
# Environment files
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
# Build outputs
dist/
build/
# OS-specific files
.DS_Store
Thumbs.db
# Test plugins
test-plugins/
*.jar
# IDE files
.idea/
.vscode/
*.swp
```
## Conclusion
Following these Git practices will help maintain code quality and enable collaboration as the PlugSnatcher project grows. Adjust these guidelines as needed based on team preferences and project requirements.