bedrockplus 0.1.0.dev1__py3-none-win_amd64.whl

bedrockplus/_assets/tools/init_python_plugin.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Create a minimal, immediately packageable BedrockPlus Python plugin."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import tempfile
+
+
+class InitError(RuntimeError):
+    pass
+
+
+WINDOWS_RESERVED = {
+    "con", "prn", "aux", "nul", "clock$",
+    *(f"com{number}" for number in range(1, 10)),
+    *(f"lpt{number}" for number in range(1, 10)),
+}
+
+
+def _identity(display_name: str) -> tuple[str, str, str]:
+    name = display_name.strip()
+    if not name or len(name) > 80 or any(ord(character) < 32 for character in name):
+        raise InitError("plugin name must contain 1 to 80 printable characters")
+    words = re.findall(r"[A-Za-z0-9]+", name)
+    if not words:
+        raise InitError("plugin name must contain Latin letters or digits; for example: My Plugin")
+
+    plugin_id = "-".join(word.lower() for word in words)
+    if plugin_id[0].isdigit():
+        plugin_id = "plugin-" + plugin_id
+    if plugin_id.casefold() in WINDOWS_RESERVED:
+        plugin_id = "plugin-" + plugin_id
+
+    class_name = "".join(word[0].upper() + word[1:] for word in words)
+    if class_name[0].isdigit():
+        class_name = "Plugin" + class_name
+    if not class_name.casefold().endswith("plugin"):
+        class_name += "Plugin"
+    return name, plugin_id, class_name
+
+
+def create_python_plugin(parent: Path, display_name: str) -> Path:
+    name, plugin_id, class_name = _identity(display_name)
+    parent = parent.resolve()
+    if any(part.casefold() == "referenceonly" for part in parent.parts):
+        raise InitError("referenceOnly is read-only; create the plugin elsewhere")
+    if not parent.is_dir():
+        raise InitError(f"destination directory does not exist: {parent}")
+    target = parent / plugin_id
+    if target.exists() or target.is_symlink():
+        raise InitError(f"destination already exists; no files were changed: {target}")
+
+    manifest = {
+        "format_version": 1,
+        "id": plugin_id,
+        "name": name,
+        "version": "0.1.0",
+        "api_version": 1,
+        "runtime": {
+            "type": "python",
+            "entrypoint": "python/plugin.py",
+            "entry_class": class_name,
+            "python": "3.13",
+        },
+    }
+    source = f'''from bedrockplus import PluginHost
+
+
+class {class_name}:
+    id = "{plugin_id}"
+    name = {name!r}
+    version = "0.1.0"
+
+    def on_load(self, host: PluginHost) -> None:
+        self.host = host
+
+    def on_enable(self) -> None:
+        pass
+
+    def on_server_ready(self) -> None:
+        pass
+
+    def on_server_stopping(self) -> None:
+        pass
+
+    def on_disable(self) -> None:
+        pass
+
+    def on_unload(self) -> None:
+        pass
+'''
+
+    staging = Path(tempfile.mkdtemp(prefix=f".bedrockplus-{plugin_id}-", dir=parent))
+    try:
+        (staging / "python").mkdir()
+        (staging / "manifest.json").write_text(
+            json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+            newline="\n",
+        )
+        (staging / "requirements.txt").write_bytes(b"")
+        (staging / "python" / "plugin.py").write_text(
+            source,
+            encoding="utf-8",
+            newline="\n",
+        )
+        os.replace(staging, target)
+    except OSError as error:
+        raise InitError(f"could not create plugin: {error}") from error
+    finally:
+        if staging.exists():
+            shutil.rmtree(staging)
+    return target
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Create a BedrockPlus Python plugin")
+    parser.add_argument("name", help="display name used to derive the folder, ID, and class")
+    parser.add_argument("--parent", default=".", help="parent directory; defaults to the current directory")
+    arguments = parser.parse_args()
+    try:
+        target = create_python_plugin(Path(arguments.parent), arguments.name)
+    except InitError as error:
+        parser.exit(1, f"BedrockPlus plugin init failed: {error}\n")
+    print(f"Created BedrockPlus Python plugin: {target}")
+    print(
+        "Next: edit python\\plugin.py, add dependencies to requirements.txt, "
+        "then run bedrockplus plugin pack"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bedrockplus/_assets/tools/pack_plugin.py

@@ -0,0 +1,142 @@
+"""Prepare a plugin folder and build a self-contained .bppack.
+
+This is the implementation behind ``bedrockplus plugin pack``.  It deliberately
+installs dependencies only during this explicit packaging operation, never
+during server startup.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+ROOT = Path(__file__).resolve().parents[1]
+BPPACK = ROOT / "tools" / "bppack.py"
+PLUGIN_ID = re.compile(r"^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$")
+SAFE_VERSION = re.compile(r"^[0-9A-Za-z.+-]+$")
+
+
+class PackError(RuntimeError):
+    pass
+
+
+def _manifest_identity(source: Path) -> tuple[str, str]:
+    manifest_path = source / "manifest.json"
+    if not manifest_path.is_file():
+        raise PackError(f"manifest.json was not found in {source}")
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8-sig"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise PackError(f"manifest.json could not be read: {error}") from error
+    plugin_id = manifest.get("id")
+    version = manifest.get("version")
+    if not isinstance(plugin_id, str) or not plugin_id.strip():
+        raise PackError("manifest.json must contain a non-empty string id")
+    if not isinstance(version, str) or not version.strip():
+        raise PackError("manifest.json must contain a non-empty string version")
+    plugin_id = plugin_id.strip()
+    version = version.strip()
+    if not PLUGIN_ID.fullmatch(plugin_id) or not SAFE_VERSION.fullmatch(version):
+        raise PackError("manifest id or version cannot be used as a safe package filename")
+    return plugin_id, version
+
+
+def _copy_ignore(_directory: str, names: list[str]) -> set[str]:
+    ignored = {".git", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache"}
+    return {
+        name
+        for name in names
+        if name in ignored or name.endswith((".pyc", ".pyo", ".bppack"))
+    }
+
+
+def _requirements(source: Path) -> Path | None:
+    locked = source / "requirements.lock"
+    if locked.is_file():
+        return locked
+    ordinary = source / "requirements.txt"
+    return ordinary if ordinary.is_file() else None
+
+
+def _install_dependencies(requirements: Path, stage: Path) -> None:
+    vendor = stage / "python" / "vendor"
+    if vendor.exists():
+        shutil.rmtree(vendor)
+    vendor.mkdir(parents=True)
+    command = [
+        sys.executable,
+        "-I",
+        "-m",
+        "pip",
+        "install",
+        "--isolated",
+        "--requirement",
+        str(requirements),
+        "--target",
+        str(vendor),
+        "--prefer-binary",
+        "--no-compile",
+        "--disable-pip-version-check",
+        "--no-warn-script-location",
+    ]
+    print(f"Preparing dependencies declared by {requirements.name}...")
+    completed = subprocess.run(command, check=False, cwd=requirements.parent)
+    if completed.returncode != 0:
+        raise PackError(f"dependency installation failed with exit code {completed.returncode}")
+    for cache in vendor.rglob("__pycache__"):
+        if cache.is_dir():
+            shutil.rmtree(cache)
+
+
+def pack(source: Path, output: Path | None) -> Path:
+    source = source.resolve()
+    if not source.is_dir():
+        raise PackError(f"plugin source directory does not exist: {source}")
+    plugin_id, version = _manifest_identity(source)
+    output = (output or source / f"{plugin_id}-{version}.bppack").resolve()
+    if output.suffix.casefold() != ".bppack":
+        raise PackError("output filename must use the .bppack extension")
+    if output.parent != source and not output.parent.exists():
+        output.parent.mkdir(parents=True)
+
+    with tempfile.TemporaryDirectory(prefix="bedrockplus-pack-") as temporary:
+        stage = Path(temporary) / "payload"
+        shutil.copytree(source, stage, symlinks=True, ignore=_copy_ignore)
+        requirements = _requirements(source)
+        if requirements is not None:
+            _install_dependencies(requirements, stage)
+        else:
+            print("No requirements.lock or requirements.txt found; packaging without external dependencies.")
+        completed = subprocess.run(
+            [sys.executable, "-I", "-B", str(BPPACK), "build", str(stage), str(output), "--force"],
+            check=False,
+        )
+        if completed.returncode != 0:
+            raise PackError(f"package validation/build failed with exit code {completed.returncode}")
+
+    print(f"BedrockPlus plugin ready: {output}")
+    return output
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Build a self-contained BedrockPlus plugin package")
+    parser.add_argument("source", nargs="?", default=".", help="plugin folder; defaults to the current directory")
+    parser.add_argument("--output", help="output .bppack; defaults beside manifest.json")
+    arguments = parser.parse_args()
+    try:
+        pack(Path(arguments.source), Path(arguments.output) if arguments.output else None)
+        return 0
+    except PackError as error:
+        print(f"BedrockPlus pack failed: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())