Initial commit: PlugSnatcher basic structure
This commit is contained in:
commit
d9cf404402
46 files changed
+10036
No files matched your search
@@ -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.
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
description:
|
||||
globs:
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Your rule content
|
||||
|
||||
- You can @ files here
|
||||
- You can use markdown but dont have to
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user