@mafly/bdev-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mafly
+
+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

@@ -1,3 +1,226 @@
-# Temporary Holding Version
+# bdev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A simple CLI tool for Minecraft Bedrock Edition addon development.
+
+---
+
+## Features
+
+- **TypeScript Compilation**: Bundles scripts with `esbuild`, keeping `@minecraft/*` modules external.
+- **In-Game Hot Reload**: Built-in WebSocket server triggers `/reload` in your active Minecraft world on file save.
+- **Live Sync**: Symlinks behavior and resource packs to Bedrock `development_*_packs` folders.
+- **Manifest Management**: Generates and validates `manifest.json` files with v4 UUIDs.
+- **Distribution Packaging**: Compresses packs into `.mcaddon` and `.mcpack` files.
+- **Diagnostics**: Checks Node.js, npm, Bun, and `com.mojang` path detection.
+
+---
+
+## Installation
+
+### Option 1: Via NPM (Recommended)
+
+```bash
+npm install -g @mafly/bdev-cli
+```
+
+Or run directly without installing:
+
+```bash
+npx @mafly/bdev-cli --help
+```
+
+### Option 2: Standalone Binary
+
+Download the compiled binary from [GitHub Releases](https://github.com/Mafly/bdev/releases).
+
+Binary naming format: `bdev-<version>-<os>-<arch>`
+
+| Platform              | Binary                           |
+| --------------------- | -------------------------------- |
+| Windows (x64)         | `bdev-<version>-windows-x64.exe` |
+| Linux (x64)           | `bdev-<version>-linux-x64`       |
+| Linux (arm64)         | `bdev-<version>-linux-arm64`     |
+| macOS (Apple Silicon) | `bdev-<version>-macos-arm64`     |
+| macOS (Intel)         | `bdev-<version>-macos-x64`       |
+
+On Linux/macOS:
+
+```bash
+chmod +x bdev-<version>-linux-x64
+sudo mv bdev-<version>-linux-x64 /usr/local/bin/bdev
+```
+
+### Option 3: From Source (Bun)
+
+```bash
+git clone https://github.com/Mafly/bdev.git
+cd bdev
+bun install
+bun run build
+./bdev --help
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Create project
+bdev init my-addon
+cd my-addon
+
+# 2. (Optional) Set com.mojang path if not detected automatically
+bdev set-path "C:\Users\<user>\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang"
+
+# 3. Start dev server
+bdev dev
+```
+
+In your Minecraft world (Cheats Enabled):
+
+```
+/connect localhost:8000
+```
+
+Saving any script file will rebuild and trigger `/reload` in game.
+
+<details>
+<summary><b>Project Structure</b></summary>
+
+```
+my-addon/
+├── behavior_pack/
+│   ├── manifest.json
+│   └── pack_icon.png
+├── resource_pack/
+│   ├── manifest.json
+│   ├── pack_icon.png
+│   └── texts/en_US.lang
+├── src/
+│   └── main.ts
+├── bdev.json
+├── package.json
+├── tsconfig.json
+└── .gitignore
+```
+
+</details>
+
+---
+
+## Command Reference
+
+<details>
+<summary><b>bdev init [directory]</b> — Scaffold project</summary>
+
+```bash
+bdev init my-addon [options]
+```
+
+| Flag                | Description                             | Default           |
+| ------------------- | --------------------------------------- | ----------------- |
+| `-n, --name <name>` | Project and pack name                   | Directory name    |
+| `-d, --desc <desc>` | Description in manifest.json            | Addon description |
+| `-p, --path <path>` | Save com.mojang path to bdev.json       | Auto-detected     |
+| `--no-rp`           | Behavior pack only (skip resource pack) | Both packs        |
+| `--lang <ts\|js>`   | Script language (`ts` or `js`)          | `ts`              |
+
+</details>
+
+<details>
+<summary><b>bdev dev [directory]</b> — Live watch and Hot Reload</summary>
+
+```bash
+bdev dev [options]
+```
+
+Symlinks packs to `com.mojang`, starts WebSocket server, and watches for changes.
+
+| Flag                | Description                      | Default                |
+| ------------------- | -------------------------------- | ---------------------- |
+| `-p, --path <path>` | Custom com.mojang directory path | Config / auto-detected |
+| `-s, --save`        | Save `-p` path into `bdev.json`  | `false`                |
+| `-P, --port <port>` | WebSocket port for `/connect`    | `8000`                 |
+| `--no-ws`           | Disable WebSocket server         | Enabled                |
+| `--no-link`         | Skip creating directory symlinks | Symlinked              |
+
+</details>
+
+<details>
+<summary><b>bdev build [directory]</b> — Compile TypeScript</summary>
+
+```bash
+bdev build [options]
+```
+
+Bundles `src/**/*.ts` into `behavior_pack/scripts/main.js` and validates `manifest.json`.
+
+| Flag             | Description               | Default            |
+| ---------------- | ------------------------- | ------------------ |
+| `-m, --minify`   | Minify bundled JavaScript | `false`            |
+| `--no-sourcemap` | Disable sourcemap output  | Sourcemaps enabled |
+
+</details>
+
+<details>
+<summary><b>bdev package [directory]</b> — Build and export archives</summary>
+
+```bash
+bdev package [options]
+# alias: bdev deploy
+```
+
+Creates distribution packages inside `dist/`:
+
+- `dist/<name>.mcaddon` (contains both BP and RP)
+- `dist/<name>_BP.mcpack`
+- `dist/<name>_RP.mcpack`
+
+| Flag                 | Description      | Default      |
+| -------------------- | ---------------- | ------------ |
+| `-o, --output <dir>` | Output directory | `dist/`      |
+| `-n, --name <name>`  | File name prefix | Project name |
+
+</details>
+
+<details>
+<summary><b>bdev set-path & config</b> — Manage configuration</summary>
+
+```bash
+# Set Bedrock com.mojang path locally (bdev.json)
+bdev set-path "C:\path\to\com.mojang"
+
+# Set Bedrock path globally (~/.bdev/config.json)
+bdev set-path "C:\path\to\com.mojang" -g
+
+# View configuration
+bdev config get
+bdev config get mojangPath
+
+# Set generic config key
+bdev config set <key> <value> [-g]
+```
+
+</details>
+
+<details>
+<summary><b>bdev doctor</b> — Environment diagnostics</summary>
+
+```bash
+bdev doctor [-p <path>]
+```
+
+Verifies:
+
+- Operating system platform
+- Node.js runtime version
+- npm package manager availability
+- Bun runtime availability
+- Minecraft Bedrock `com.mojang` path detection
+  </details>
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/dist/commands/build.d.ts

@@ -0,0 +1,6 @@
+export interface BuildOptions {
+    minify?: boolean;
+    sourcemap?: boolean;
+    watch?: boolean;
+}
+export declare function buildCommand(dirArg?: string, options?: BuildOptions): Promise<boolean>;

package/dist/commands/build.js

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import path from "node:path";
+import { runBuild } from "../utils/bundler.js";
+import { validateManifest } from "../utils/manifest.js";
+import { logger } from "../utils/logger.js";
+export async function buildCommand(dirArg, options = {}) {
+    const rootDir = path.resolve(dirArg || ".");
+    const bpDir = path.join(rootDir, "behavior_pack");
+    const bpManifestPath = path.join(bpDir, "manifest.json");
+    // 1. Validate Behavior Pack Manifest
+    if (!fs.existsSync(bpManifestPath)) {
+        logger.error(`Behavior pack manifest not found: ${bpManifestPath}`);
+        return false;
+    }
+    logger.info("Validating manifest.json files...");
+    const bpValidation = validateManifest(bpManifestPath);
+    if (!bpValidation.valid) {
+        logger.error("Behavior pack manifest validation failed:");
+        for (const err of bpValidation.errors) {
+            console.error(`  - ${err}`);
+        }
+        return false;
+    }
+    logger.success("Behavior pack manifest valid");
+    // Validate Resource Pack Manifest if exists
+    const rpDir = path.join(rootDir, "resource_pack");
+    const rpManifestPath = path.join(rpDir, "manifest.json");
+    if (fs.existsSync(rpManifestPath)) {
+        const rpValidation = validateManifest(rpManifestPath);
+        if (!rpValidation.valid) {
+            logger.error("Resource pack manifest validation failed:");
+            for (const err of rpValidation.errors) {
+                console.error(`  - ${err}`);
+            }
+            return false;
+        }
+        logger.success("Resource pack manifest valid");
+    }
+    // 2. Determine if TypeScript compilation is needed
+    const srcDir = path.join(rootDir, "src");
+    if (!fs.existsSync(srcDir)) {
+        logger.info("No 'src' directory found. Skipping script compilation.");
+        return true;
+    }
+    // Find entry points
+    let entryPoint = "";
+    if (fs.existsSync(path.join(srcDir, "main.ts"))) {
+        entryPoint = path.join(srcDir, "main.ts");
+    }
+    else if (fs.existsSync(path.join(srcDir, "index.ts"))) {
+        entryPoint = path.join(srcDir, "index.ts");
+    }
+    else {
+        // Look for any .ts file
+        const files = fs.readdirSync(srcDir).filter((f) => f.endsWith(".ts"));
+        if (files.length > 0) {
+            entryPoint = path.join(srcDir, files[0]);
+        }
+    }
+    if (!entryPoint) {
+        logger.warn("No TypeScript entry point (.ts) found in 'src/'. Skipping bundling.");
+        return true;
+    }
+    const outDir = path.join(bpDir, "scripts");
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+    const outFile = path.join(outDir, "main.js");
+    const spinner = logger.spinner(`Bundling ${path.relative(rootDir, entryPoint)} -> ${path.relative(rootDir, outFile)}...`);
+    try {
+        const startTime = Date.now();
+        await runBuild({
+            entryPoints: [entryPoint],
+            outfile: outFile,
+            bundle: true,
+            format: "esm",
+            target: "es2020",
+            platform: "neutral",
+            minify: options.minify ?? false,
+            sourcemap: options.sourcemap ?? true,
+            external: [
+                "@minecraft/*",
+            ],
+        });
+        const duration = Date.now() - startTime;
+        spinner.succeed(`Build succeeded in ${duration}ms (${path.relative(rootDir, outFile)})`);
+        return true;
+    }
+    catch (err) {
+        spinner.fail("Build failed");
+        logger.error(err.message);
+        return false;
+    }
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,7 @@
+export interface ConfigOptions {
+    global?: boolean;
+    dir?: string;
+}
+export declare function setConfigCommand(key: string, value: string, options?: ConfigOptions): Promise<void>;
+export declare function getConfigCommand(key?: string, options?: ConfigOptions): Promise<void>;
+export declare function setPathCommand(inputPath: string, options?: ConfigOptions): Promise<void>;

package/dist/commands/config.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import fs from "node:fs";
+import { loadGlobalConfig, loadMergedConfig, saveConfig, getGlobalConfigPath, getLocalConfigPath, } from "../utils/config.js";
+import { logger } from "../utils/logger.js";
+export async function setConfigCommand(key, value, options = {}) {
+    const normalizedKey = key === "path" || key === "mojang-path" ? "mojangPath" : key;
+    if (normalizedKey === "mojangPath") {
+        const resolved = path.resolve(value);
+        if (!fs.existsSync(resolved)) {
+            logger.warn(`Target path does not exist on disk: ${resolved}`);
+        }
+        value = resolved;
+    }
+    const updates = {
+        [normalizedKey]: value,
+    };
+    const savedFile = saveConfig(updates, {
+        global: options.global,
+        dir: options.dir,
+    });
+    logger.success(`Set ${normalizedKey} = "${value}" in ${savedFile}`);
+}
+export async function getConfigCommand(key, options = {}) {
+    const conf = options.global
+        ? loadGlobalConfig()
+        : loadMergedConfig(options.dir);
+    if (key) {
+        const normalizedKey = key === "path" || key === "mojang-path" ? "mojangPath" : key;
+        const val = conf[normalizedKey];
+        if (val !== undefined) {
+            console.log(val);
+        }
+        else {
+            logger.info(`Key '${key}' is not set.`);
+        }
+    }
+    else {
+        logger.info("Current configuration:");
+        console.log(JSON.stringify(conf, null, 2));
+        logger.info(`Local config file: ${getLocalConfigPath(options.dir)}`);
+        logger.info(`Global config file: ${getGlobalConfigPath()}`);
+    }
+}
+export async function setPathCommand(inputPath, options = {}) {
+    await setConfigCommand("mojangPath", inputPath, options);
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,8 @@
+export interface DevOptions {
+    path?: string;
+    link?: boolean;
+    save?: boolean;
+    port?: number;
+    ws?: boolean;
+}
+export declare function devCommand(dirArg?: string, options?: DevOptions): Promise<void>;

package/dist/commands/dev.js

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import chokidar from "chokidar";
+import pc from "picocolors";
+import { buildCommand } from "./build.js";
+import { findMojangPath, linkPack } from "../utils/mojang.js";
+import { saveConfig } from "../utils/config.js";
+import { BedrockHotReloadServer } from "../utils/wsserver.js";
+import { logger } from "../utils/logger.js";
+import { validateManifest } from "../utils/manifest.js";
+export async function devCommand(dirArg, options = {}) {
+    const rootDir = path.resolve(dirArg || ".");
+    const bpDir = path.join(rootDir, "behavior_pack");
+    const rpDir = path.join(rootDir, "resource_pack");
+    const hasBp = fs.existsSync(bpDir);
+    const hasRp = fs.existsSync(rpDir);
+    if (!hasBp && !hasRp) {
+        logger.error(`No behavior_pack or resource_pack found in ${rootDir}. Run 'bdev init' first.`);
+        process.exit(1);
+    }
+    const folderName = path.basename(rootDir);
+    // If --save and path provided, save to bdev.json
+    if (options.save && options.path) {
+        const resolvedPath = path.resolve(options.path);
+        saveConfig({ mojangPath: resolvedPath }, { dir: rootDir });
+        logger.success(`Saved mojang path to bdev.json: ${resolvedPath}`);
+    }
+    // 1. Initial build
+    logger.info("Executing initial build...");
+    const initialBuildOk = await buildCommand(rootDir);
+    if (!initialBuildOk) {
+        logger.warn("Initial build had warnings or errors. Continuing dev server...");
+    }
+    // 2. Setup symlinks to com.mojang
+    const shouldLink = options.link !== false;
+    if (shouldLink) {
+        const mojang = findMojangPath(options.path, rootDir);
+        if (!mojang) {
+            logger.warn("Minecraft com.mojang directory not found.");
+            logger.warn("Tip: Set with 'bdev set-path <path>' or pass '-p <path>' or 'BEDROCK_MOJANG_PATH'.");
+            logger.warn("Continuing in watch-only mode (without symlinking).");
+        }
+        else {
+            logger.info(`Found com.mojang location (${mojang.type}): ${mojang.root}`);
+            if (hasBp) {
+                const destBp = path.join(mojang.devBehaviorPacks, `${folderName}_BP`);
+                try {
+                    linkPack(bpDir, destBp);
+                    logger.success(`Linked Behavior Pack -> ${destBp}`);
+                }
+                catch (err) {
+                    logger.error(`Failed to link Behavior Pack: ${err.message}`);
+                }
+            }
+            if (hasRp) {
+                const destRp = path.join(mojang.devResourcePacks, `${folderName}_RP`);
+                try {
+                    linkPack(rpDir, destRp);
+                    logger.success(`Linked Resource Pack -> ${destRp}`);
+                }
+                catch (err) {
+                    logger.error(`Failed to link Resource Pack: ${err.message}`);
+                }
+            }
+        }
+    }
+    // 3. Start WebSocket Hot Reload server
+    const enableWs = options.ws !== false;
+    let hotReloadServer = null;
+    let wsPort = options.port ? Number(options.port) : 8000;
+    if (enableWs) {
+        try {
+            hotReloadServer = new BedrockHotReloadServer(wsPort);
+            wsPort = await hotReloadServer.start();
+            console.log();
+            logger.info(pc.bold(`Hot Reload WebSocket server active on ${pc.cyan(`ws://localhost:${wsPort}`)}`));
+            logger.info(pc.yellow(`To connect in Minecraft (cheats on): ${pc.bold(`/connect localhost:${wsPort}`)}`));
+            console.log();
+        }
+        catch (err) {
+            logger.error(`Failed to start WebSocket hot reload server: ${err.message}`);
+        }
+    }
+    // 4. Start chokidar watcher
+    const watchPaths = [];
+    const srcDir = path.join(rootDir, "src");
+    if (fs.existsSync(srcDir)) {
+        watchPaths.push(srcDir);
+    }
+    if (hasBp) {
+        watchPaths.push(bpDir);
+    }
+    if (hasRp) {
+        watchPaths.push(rpDir);
+    }
+    logger.info(`Starting file watcher on: ${watchPaths.map((p) => path.relative(rootDir, p)).join(", ")}`);
+    logger.info("Press Ctrl+C to stop.");
+    let isRebuilding = false;
+    let rebuildTimeout = null;
+    const watcher = chokidar.watch(watchPaths, {
+        ignored: [
+            /(^|[/\\])\../, // dotfiles
+            /node_modules/,
+            /dist/,
+            /behavior_pack[/\\]scripts[/\\]main\.js(\.map)?$/, // ignore build output
+        ],
+        persistent: true,
+        ignoreInitial: true,
+    });
+    const triggerRebuild = (filePath) => {
+        const rel = path.relative(rootDir, filePath);
+        logger.info(`Change detected in ${rel}`);
+        if (rebuildTimeout) {
+            clearTimeout(rebuildTimeout);
+        }
+        rebuildTimeout = setTimeout(async () => {
+            if (isRebuilding)
+                return;
+            isRebuilding = true;
+            try {
+                if (filePath.endsWith("manifest.json")) {
+                    const res = validateManifest(filePath);
+                    if (res.valid) {
+                        logger.success(`Validated ${rel}`);
+                    }
+                    else {
+                        logger.error(`Invalid manifest in ${rel}:`);
+                        res.errors.forEach((e) => console.error(`  - ${e}`));
+                    }
+                }
+                // Run build if src changed or if script output needed
+                if (fs.existsSync(srcDir)) {
+                    const buildOk = await buildCommand(rootDir);
+                    if (buildOk && hotReloadServer) {
+                        if (hotReloadServer.clientCount > 0) {
+                            hotReloadServer.reload();
+                            logger.success("Sent /reload to Minecraft via WebSocket");
+                        }
+                        else {
+                            logger.info(`Hot reload skipped (no Minecraft client connected; run /connect localhost:${wsPort} in game)`);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger.error(`Error during rebuild: ${err.message}`);
+            }
+            finally {
+                isRebuilding = false;
+            }
+        }, 100);
+    };
+    watcher.on("change", triggerRebuild);
+    watcher.on("add", triggerRebuild);
+    watcher.on("unlink", triggerRebuild);
+    // Handle graceful exit
+    process.on("SIGINT", async () => {
+        logger.info("Stopping dev server and watcher...");
+        await watcher.close();
+        if (hotReloadServer) {
+            await hotReloadServer.stop();
+        }
+        process.exit(0);
+    });
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctorCommand(customPath?: string): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,84 @@
+import { execSync } from "node:child_process";
+import os from "node:os";
+import pc from "picocolors";
+import { findMojangPath } from "../utils/mojang.js";
+import { logger } from "../utils/logger.js";
+function checkCommand(cmd) {
+    try {
+        const out = execSync(cmd, { stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8" });
+        return out.trim();
+    }
+    catch {
+        return null;
+    }
+}
+export async function doctorCommand(customPath) {
+    console.log(pc.bold("\n Bedrock Dev (bdev) Environment Doctor\n"));
+    const checks = [];
+    // OS Info
+    const platform = os.platform();
+    const release = os.release();
+    checks.push({
+        name: "Operating System",
+        ok: true,
+        details: `${platform} (${release})`,
+    });
+    // Node.js
+    const nodeVersion = process.version;
+    checks.push({
+        name: "Node.js Runtime",
+        ok: Boolean(nodeVersion),
+        details: nodeVersion || "Not found",
+    });
+    // npm
+    const npmVersion = checkCommand("npm --version");
+    checks.push({
+        name: "npm Package Manager",
+        ok: Boolean(npmVersion),
+        details: npmVersion ? `v${npmVersion}` : "Not found in PATH",
+    });
+    // Bun
+    const bunVersion = checkCommand("bun --version");
+    checks.push({
+        name: "Bun Runtime",
+        ok: Boolean(bunVersion),
+        details: bunVersion ? `v${bunVersion}` : "Not found in PATH (optional)",
+    });
+    // Minecraft Bedrock com.mojang folder
+    const mojang = findMojangPath(customPath);
+    if (mojang) {
+        checks.push({
+            name: "Minecraft Bedrock (com.mojang)",
+            ok: true,
+            details: `Found (${mojang.type}): ${mojang.root}`,
+        });
+    }
+    else {
+        checks.push({
+            name: "Minecraft Bedrock (com.mojang)",
+            ok: false,
+            details: "Directory not found. Expected in Windows UWP LocalAppData or specify via BEDROCK_MOJANG_PATH",
+        });
+    }
+    // Display results
+    let allPassed = true;
+    for (const item of checks) {
+        const symbol = item.ok ? pc.green("✔") : pc.red("✖");
+        const nameStr = pc.bold(item.name.padEnd(32));
+        console.log(`  ${symbol} ${nameStr} ${item.details}`);
+        if (!item.ok && item.name !== "Minecraft Bedrock (com.mojang)") {
+            allPassed = false;
+        }
+    }
+    console.log();
+    if (!mojang) {
+        logger.warn("Notice: com.mojang was not detected automatically. If you develop on Windows or use a custom path, export BEDROCK_MOJANG_PATH='/path/to/com.mojang'.");
+    }
+    if (allPassed) {
+        logger.success("Core development environment is ready!");
+    }
+    else {
+        logger.warn("Some environment checks did not pass. Review the items marked with ✖ above.");
+    }
+    console.log();
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,8 @@
+export interface InitOptions {
+    name?: string;
+    desc?: string;
+    rp: boolean;
+    lang: "ts" | "js";
+    path?: string;
+}
+export declare function initCommand(targetDirArg: string | undefined, options: InitOptions): Promise<void>;