@modcafe/milkbucket 1.0.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,26 @@
+name: Publish to npm
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Publish package
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,309 @@
+# 🥛 milkbucket
+
+**Milkbucket** is an internal CLI tool by **Modcafe** for tooling, debugging, and managing Minecraft mods and datapacks.
+
+It is built with **Node.js** and **JavaScript**.
+
+---
+
+# Installation
+
+## 1. Install Node.js and npm
+
+Milkbucket requires **Node.js** and **npm**.
+
+### macOS
+
+Using Homebrew:
+
+```bash
+brew install node
+```
+
+Verify the installation:
+
+```bash
+node --version
+npm --version
+```
+
+### Windows
+
+Using `winget`:
+
+```powershell
+winget install OpenJS.NodeJS
+```
+
+Verify the installation:
+
+```powershell
+node --version
+npm --version
+```
+
+### Linux
+
+On Debian/Ubuntu-based distributions:
+
+```bash
+sudo apt update
+sudo apt install nodejs npm
+```
+
+Verify the installation:
+
+```bash
+node --version
+npm --version
+```
+
+---
+
+## 2. Clone Milkbucket
+
+Clone the repository and enter its directory:
+
+```bash
+git clone https://github.com/Modcafe/milkbucket.git
+cd milkbucket
+```
+
+Then link Milkbucket as a global CLI:
+
+```bash
+npm link
+```
+
+### If `npm link` fails
+
+If npm does not have permission to create the global link, configure a user-local npm directory:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Then run:
+
+```bash
+npm link
+```
+
+---
+
+## 3. Verify the installation
+
+Check whether Milkbucket is available:
+
+```bash
+milkbucket --version
+```
+
+You can also display the available commands:
+
+```bash
+milkbucket --help
+```
+
+---
+
+# Commands
+
+> This section documents all available Milkbucket commands.
+
+## `help`
+
+Displays a list of available commands and their descriptions.
+
+```bash
+milkbucket help
+```
+
+Aliases:
+
+```bash
+milkbucket -h
+milkbucket --help
+```
+
+---
+
+## `version`
+
+Displays the installed Milkbucket version.
+
+```bash
+milkbucket version
+```
+
+Aliases:
+
+```bash
+milkbucket -v
+milkbucket --version
+```
+
+---
+
+## `info` (comming soon)
+
+Displays information about the current project and environment.
+
+```bash
+milkbucket info
+```
+
+---
+
+## `project` (comming soon)
+
+Tools for inspecting and working with the current Minecraft project.
+
+```bash
+milkbucket project
+```
+
+### `project detect` (comming soon)
+
+Detects the type and configuration of the current project.
+
+```bash
+milkbucket project detect
+```
+
+### `project validate` (comming soon)
+
+Checks the current project for common configuration problems.
+
+```bash
+milkbucket project validate
+```
+
+---
+
+## `build` (comming soon)
+
+Builds the current Minecraft project.
+
+```bash
+milkbucket build
+```
+
+---
+
+## `deps` (comming soon)
+
+Tools for inspecting project dependencies.
+
+```bash
+milkbucket deps
+```
+
+### `deps list` (comming soon)
+
+Lists the dependencies of the current project.
+
+```bash
+milkbucket deps list
+```
+
+### `deps check` (comming soon)
+
+Checks whether the project's dependencies are valid.
+
+```bash
+milkbucket deps check
+```
+
+---
+
+## `logs` (comming soon)
+
+Tools for working with Minecraft logs.
+
+```bash
+milkbucket logs
+```
+
+### `logs latest` (comming soon)
+
+Displays or analyzes the latest log.
+
+```bash
+milkbucket logs latest
+```
+
+---
+
+## `crash` (comming soon)
+
+Analyzes the latest Minecraft crash report.
+
+```bash
+milkbucket crash
+```
+
+---
+
+## `team` (comming soon)
+
+Tools for Modcafe development teams.
+
+```bash
+milkbucket team
+```
+
+### `team doctor` (comming soon)
+
+Checks the local development environment.
+
+```bash
+milkbucket team doctor
+```
+
+---
+
+# Updating
+
+To update your local Milkbucket installation, pull the latest changes from GitHub:
+
+```bash
+cd milkbucket
+git pull
+npm link
+```
+
+> [!TIP]
+> You only need to configure the npm prefix once. After that, updating Milkbucket only requires `git pull` and `npm link`.
+
+---
+
+# Development
+
+Milkbucket is developed using Node.js and JavaScript.
+
+The repository is structured roughly as follows:
+
+```text
+milkbucket/
+├── cli.js
+├── package.json
+├── commands/
+│   ├── help.js
+│   ├── version.js
+│   └── ...
+└── lib/
+    ├── commandInfo.json
+    └── ...
+```
+
+New commands should be added to the `commands/` directory and registered in the command metadata.
+
+---
+
+# License
+
+Internal Modcafe tooling.

package/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import packageJson from "./package.json" with { type: "json" };
+import metadata from "./metadata.json" with { type: "json" };
+
+import help from "./commands/help.js";
+import getVersion from "./commands/version.js";
+
+const args = process.argv.slice(2);
+const command = args.shift();
+
+switch (command) {
+    case "help":
+    case "--help":
+    case "-h":
+        help(args);
+        break;
+
+    case "version":
+    case "--version":
+    case "-v":
+        getVersion(args);
+        break;
+    
+    
+/**********************************/
+    case undefined:
+        console.log(`Welcome to ${metadata.displayName} v${packageJson.version}.
+Type "${metadata.name} ${metadata.commands.help}" for more information.`);
+        break;
+
+    default:
+        console.error(`Unknown command: ${command}\nUse ${metadata.name} ${metadata.commands.help} for a list of useable commands.`);
+        process.exit(1);
+}

package/commandMetadata.json

@@ -0,0 +1,27 @@
+{
+    "_TEMPLATE_FOR_COMMANDS": {
+        "lastUpdated": "1.0.0",
+        "firstAdded": "1.0.0",
+        "contributors": ["ContributorA", "ContributorB"],
+        "description": "This is a Command Description.",
+        "aliases": ["--template", "-t"],
+        "args": "[arg1|arg2] <arg3|arg4|arg5>"
+    },
+
+
+
+    "help": {
+        "lastUpdated": "1.0.0",
+        "firstAdded": "1.0.0",
+        "contributors": ["Intensed"],
+        "description": "Shows a list of all Commands and Options.",
+        "aliases": ["--help", "-h"]
+    },
+    "version": {
+        "lastUpdated": "1.0.0",
+        "firstAdded": "1.0.0",
+        "contributors": ["Intensed"],
+        "description": "Show which version of milkbucket you have installed",
+        "aliases": ["--version", "-v"]
+    }
+}

package/commands/help.js

@@ -0,0 +1,46 @@
+import { getCommandVersionText, getCommandHelpText } from "../lib/commandInfo.js";
+//import packageJson from "../package.json" with { type: "json" };
+import metadata from "../metadata.json" with { type: "json" };
+import commandMetadata from "../commandMetadata.json" with { type: "json" };
+import optionMetadata from "../optionMetadata.json" with { type: "json" };
+
+export default function help(args) {
+    switch (args[0]) {
+        case "-v":
+        case "--version":
+            console.log(getCommandVersionText("help"));
+            break;
+        
+        case "-h":
+        case "--help":
+            console.log(getCommandHelpText("help"));
+            break;
+
+        default:
+            let commandsText = "";
+
+            for (const [commandName, info] of Object.entries(commandMetadata)) {
+                if (commandName.startsWith("_")) continue;
+
+                commandsText += `                    ${commandName.padEnd(24)}${info.description}\n`
+            }
+
+            let optionsText = "";
+
+            for (const [optionName, info] of Object.entries(optionMetadata)) {
+                if (optionName.startsWith("_")) continue;
+                const optionNameWithAlias = `${optionName}, ${info.aliases[0]}`;
+                optionsText += `                    ${optionNameWithAlias.padEnd(24)}${info.description}\n`
+            }
+
+            console.log(`
+                Usage: ${metadata.name} [command] <args> <options>
+            
+                Commands:
+${commandsText}
+                
+                Options:
+${optionsText}
+                `);        
+    }
+};

package/commands/version.js

@@ -0,0 +1,20 @@
+import { getCommandVersionText, getCommandHelpText } from "../lib/commandInfo.js";
+import packageJson from "../package.json" with { type: "json" };
+import metadata from "../metadata.json" with { type: "json" };
+
+export default function help(args) {
+    switch (args[0]) {
+        case "-v":
+        case "--version":
+            console.log(getCommandVersionText("version"));
+            break;
+        
+        case "-h":
+        case "--help":
+            console.log(getCommandHelpText("version"));
+            break;
+
+        default:
+            console.log(`v${packageJson.version}`);        
+    }
+};

package/lib/commandInfo.js

@@ -0,0 +1,33 @@
+import commandMetadata from "../commandMetadata.json" with { type: "json" };
+import packageJson from "../package.json" with { type: "json" };
+import metadata from "../metadata.json" with { type: "json" };
+
+export function getCommandVersionText(commandName) {
+    const lastUpdated = commandMetadata[commandName].lastUpdated;
+    const firstAdded = commandMetadata[commandName].firstAdded;
+    const contributors = commandMetadata[commandName].contributors;
+
+    return `${metadata.name} ${commandName}
+
+    last Updated:   ${lastUpdated}
+    first Added:    ${firstAdded}
+    Contributors:   ${contributors.join(", ")}
+        
+For more Information, use ${metadata.name} ${commandName} -h`;
+}
+
+export function getCommandHelpText(commandName) {
+    const description = commandMetadata[commandName].description;
+    const rawCommandArgs = commandMetadata[commandName].args;
+
+    let commandArgs = commandName;
+    if (rawCommandArgs) {
+        commandArgs = `${commandName} ${rawCommandArgs}`;
+    }
+    
+    return `${metadata.name} ${commandArgs}
+    
+    ${description}
+    
+For more Information, use ${metadata.name} ${commandName} -v`;
+}

package/metadata.json

@@ -0,0 +1,13 @@
+{
+    "displayName": "Milkbucket",
+    "name": "milkbucket",
+    "description": "Milkbucket is a internal CLI-Tool developed from and for Modcafe and their Members, to test, debug and tool code.",
+    "commands": {
+        "help": "--help",
+        "version": "--version"
+    },
+    "options": {
+        "help": "-h",
+        "version": "-v"
+    }
+}

package/optionMetadata.json

@@ -0,0 +1,17 @@
+{
+    "_TEMPLATE_FOR_OPTIONS": {
+        "description": "This is a Option Description.",
+        "aliases": ["--template", "-t"]
+    },
+
+
+
+    "-h": {
+        "description": "Show a list of Arguments and syntax aswell as a description.",
+        "aliases": ["--help"]
+    },
+    "-v": {
+        "description": "Show the latest and first version of a Command.",
+        "aliases": ["--version"]
+    }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+    "name": "@modcafe/milkbucket",
+    "version": "1.0.0",
+    "description": "Internal CLI tool by Modcafe for developing, testing and debugging Minecraft mods and datapacks.",
+    "type": "module",
+    "bin": {
+        "milkbucket": "./cli.js"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Modcafe/milkbucket.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Modcafe/milkbucket/issues"
+    },
+    "homepage": "https://github.com/Modcafe/milkbucket"
+}

package/template.txt

@@ -0,0 +1,24 @@
+// Command Template
+// Make sure to go to ../commandMetadata.json in order to let "-v/--version" and "-h/--help" work.
+// You need also to add commandMetadata to the json so the command shows up in milkbucket help.
+
+import { getCommandVersionText, getCommandHelpText } from "../lib/commandInfo.js";
+import packageJson from "../package.json" with { type: "json" };
+import metadata from "../metadata.json" with { type: "json" };
+
+export default function help(args) {
+    switch (args[0]) {
+        case "-v":
+        case "--version":
+            console.log(getCommandVersionText("COMMAND_NAME_HERE"));
+            break;
+        
+        case "-h":
+        case "--help":
+            console.log(getCommandHelpText("COMMAND_NAME_HERE"));
+            break;
+
+        default:
+            // ACTIONS HERE
+    }
+};