{"id":29567312,"url":"https://github.com/ch99q/pluggy","last_synced_at":"2026-04-19T04:35:29.918Z","repository":{"id":305207984,"uuid":"1020389842","full_name":"ch99q/pluggy","owner":"ch99q","description":"A command-line tool for Minecraft plugin development.","archived":false,"fork":false,"pushed_at":"2025-07-18T21:29:09.000Z","size":146,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-05T04:41:04.336Z","etag":null,"topics":["buildtools","cli","java","papermc","spigot"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ch99q.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T19:43:30.000Z","updated_at":"2025-07-18T21:29:12.000Z","dependencies_parsed_at":"2025-12-26T16:04:10.484Z","dependency_job_id":null,"html_url":"https://github.com/ch99q/pluggy","commit_stats":null,"previous_names":["ch99q/pluggy"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ch99q/pluggy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch99q%2Fpluggy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch99q%2Fpluggy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch99q%2Fpluggy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch99q%2Fpluggy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ch99q","download_url":"https://codeload.github.com/ch99q/pluggy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ch99q%2Fpluggy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31995167,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buildtools","cli","java","papermc","spigot"],"created_at":"2025-07-18T23:30:51.327Z","updated_at":"2026-04-19T04:35:29.901Z","avatar_url":"https://github.com/ch99q.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n```\n ____  _                            \n|  _ \\| |_   _  __ _  __ _ _   _ \n| |_) | | | | |/ _` |/ _` | | | |\n|  __/| | |_| | (_| | (_| | |_| |\n|_|   |_|\\__,_|\\__, |\\__, |\\__, |\n               |___/ |___/ |___/ \n```\n\n# Pluggy\n\nA command-line tool for Minecraft plugin development that streamlines project initialization, dependency management, and build processes.\n\n## Overview\n\nPluggy is built around the Modrinth ecosystem, providing a cohesive workflow from project initialization through dependency resolution to final JAR packaging. Rather than being just another build tool, Pluggy leverages Modrinth as the primary source for plugin discovery, dependency management, and version compatibility, making modern Minecraft plugin development faster and more reliable.\n\n## Key Features\n\n- **Project Scaffolding**: Generates complete project structure with proper Java package hierarchy\n- **Modrinth**: Direct plugin search, installation, and version management from Modrinth\n- **Build Automation**: Handles compilation, resource bundling, and JAR creation\n- **Dependency Shading**: Configurable dependency inclusion/exclusion patterns\n- **IDE Integration**: Automatic Eclipse project file generation with proper classpaths\n- **Platform Compatibility**: Supports Paper, Bukkit, and related server implementations\n\n## Installation\n\n### Windows (PowerShell)\n```\nirm https://raw.githubusercontent.com/ch99q/pluggy/main/install.ps1 | iex\n```\n\n### Unix-like Systems (macOS, Linux)\n```\ncurl -fsSL https://raw.githubusercontent.com/ch99q/pluggy/main/install.sh | bash\n```\n\n## Command Reference\n\n### Project Lifecycle\n\n```bash\n# Initialize new project with interactive prompts\npluggy init\n\n# Initialize with specified parameters\npluggy init --name my-plugin --main com.example.MyPlugin --version 1.0.0\n\n# Build project and generate JAR\npluggy build\n```\n\n### Dependency Management\n\n```bash\n# Install all project dependencies\npluggy install\n\n# Add specific plugin from Modrinth\npluggy install worldedit\n\n# Add specific version\npluggy install placeholderapi@2.11.6\n\n# Add local JAR file\npluggy install ./libs/custom-library.jar\n\n# Add Maven dependency\npluggy install maven:net.kyori:adventure-api@4.22.0\n\n# Include pre-release versions in search\npluggy install some-plugin --beta\n\n# Remove dependency\npluggy remove worldedit\n```\n\n### Information and Discovery\n\n```bash\n# Search Modrinth repository\npluggy search \"world management\"\n\n# Get detailed plugin information\npluggy info worldedit\n\n# Show specific version details\npluggy info worldedit@7.3.15\n```\n\n### Global Options\n\n- `--verbose, -v` - Enable detailed logging output\n- `--no-color` - Disable colored terminal output  \n- `--config-file \u003cpath\u003e` - Specify alternative plugin.json location\n- `--help, -h` - Display command-specific help\n- `--version, -V` - Show Pluggy version information\n\n## Project Configuration\n\nPluggy projects are configured via `plugin.json` in the project root:\n\n```json\n{\n  \"name\": \"example-plugin\",\n  \"version\": \"1.0.0\",\n  \"main\": \"com.example.ExamplePlugin\",\n  \"description\": \"An example Minecraft plugin\",\n  \"authors\": [\"Developer Name\"],\n  \"resources\": {\n    \"config.yml\": \"./resources/config.yml\",\n    \"plugin.yml\": \"./resources/plugin.yml\"\n  },\n  \"dependencies\": {\n    \"worldedit\": \"7.3.15\",\n    \"placeholderapi\": \"2.11.6\"\n  },\n  \"shading\": {\n    \"some-library\": {\n      \"include\": [\"com/library/core/**\"],\n      \"exclude\": [\"com/library/unused/**\"]\n    }\n  },\n  \"compatibility\": {\n    \"versions\": [\"1.21.7\", \"1.21.3\"],\n    \"platforms\": [\"paper\", \"bukkit\"]\n  },\n  \"registries\": [\n    \"https://repo1.maven.org/maven2/\"\n  ]\n}\n```\n\n### Configuration Fields\n\n- **name**: Plugin identifier (used for JAR filename and plugin.yml)\n- **version**: Plugin version (semantic versioning recommended)\n- **main**: Fully qualified main class name\n- **description**: Plugin description for plugin.yml\n- **authors**: Array of author names\n- **resources**: File mappings from plugin.yml keys to local paths\n- **dependencies**: Modrinth plugin dependencies with versions\n- **shading**: Dependency inclusion/exclusion patterns for JAR packaging\n- **compatibility**: Target Minecraft versions and server platforms\n- **registries**: Additional Maven repositories for dependency resolution\n\n## Advanced Usage\n\n### Dependency Shading\n\nShading configuration allows fine-grained control over which dependency classes are included in the final JAR:\n\n```json\n{\n  \"shading\": {\n    \"library-name\": {\n      \"include\": [\"com/library/api/**\", \"com/library/util/**\"],\n      \"exclude\": [\"com/library/internal/**\"]\n    }\n  }\n}\n```\n\nPatterns use glob syntax (`**` for recursive matching, `*` for single-level wildcards).\n\n### Maven Dependencies\nPluggy supports Maven-style dependencies in the format `maven:groupId:artifactId:versionId`. This allows you to include libraries from Maven Central or other configured repositories:\n\n```bash\npluggy install maven:net.kyori:adventure-api@4.22.0\n```\nThis will download the specified version of the library and include it in your project.\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003enet.kyori\u003c/groupId\u003e\n  \u003cartifactId\u003eadventure-api\u003c/artifactId\u003e\n  \u003cversion\u003e4.22.0\u003c/version\u003e\n\u003c/dependency\u003e\n\u003crepositories\u003e\n  \u003crepository\u003e\n    \u003cid\u003esonatype-oss-snapshots1\u003c/id\u003e\n    \u003curl\u003ehttps://s01.oss.sonatype.org/content/repositories/snapshots/\u003c/url\u003e\n  \u003c/repository\u003e\n\u003c/repositories\u003e\n```\n\nThe above XML snippet would be the same as adding the following to your `plugin.json`:\n\n```json\n{\n  \"registries\": [\n    \"https://s01.oss.sonatype.org/content/repositories/snapshots/\"\n  ]\n}\n```\n\nAnd then installing the dependency with:\n\n```bash\npluggy install maven:net.kyori:adventure-api@4.22.0\n```\n\n\n### Local Dependencies\n\nReference local JAR files in your project:\n\n```bash\npluggy install ./libs/proprietary-library.jar\n```\n\nThis creates a `file:` reference in plugin.json and includes the JAR in classpath generation.\n\n### Platform Compatibility\n\nPluggy automatically downloads appropriate server JARs for compilation based on your compatibility configuration. The build system selects the most suitable platform and version combination from your specified constraints.\n\n## Build Process Details\n\nThe build process performs these operations:\n\n1. **Dependency Resolution**: Downloads and caches Modrinth dependencies\n2. **Classpath Generation**: Creates Eclipse .classpath with all dependencies\n3. **Resource Processing**: Copies and processes resource files with template variable substitution\n4. **Compilation**: Invokes javac with proper classpath and source directories\n5. **JAR Assembly**: Packages compiled classes and resources into final JAR\n6. **Plugin.yml Generation**: Automatically generates plugin.yml from project configuration\n\n### Template Variables\n\nAll resource files are processed with template variable substitution during build:\n- `$__PROJECT_NAME__$` - Project name\n- `$__PROJECT_VERSION__$` - Project version  \n- `$__PROJECT_MAIN_CLASS__$` - Main class name only\n- `$__PROJECT_PACKAGE_NAME__$` - Package name without class\n- `$__PROJECT_DESCRIPTION__$` - Project description\n\nThis allows you to use dynamic values in any resource file (config.yml, plugin.yml, etc.).\n\n## Development\n\n### Prerequisites\n- Deno 2.4.1 or later\n- Git\n\n### Building from Source\n```bash\ngit clone https://github.com/ch99q/pluggy.git\ncd pluggy\ndeno task build\n```\n\nThis generates a self-contained executable at `./bin/pluggy`.\n\n### Architecture Notes\n\nPluggy is implemented in TypeScript using Deno 2.x runtime and standard library. Key architectural decisions:\n\n- **Single binary distribution**: Compiled to native executable for each platform\n- **Zero external dependencies**: All functionality implemented using Deno standard library and JSR packages\n- **Modrinth API integration**: Direct REST API communication for plugin discovery\n- **Template-based code generation**: Parameterized file templates for project scaffolding\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and submission guidelines.\n\n## License\n\nLicensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fch99q%2Fpluggy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fch99q%2Fpluggy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fch99q%2Fpluggy/lists"}