bedrockplus 0.1.0.dev1__py3-none-win_amd64.whl

bedrockplus/_assets/tools/world_packs.py

@@ -0,0 +1,530 @@
+"""Offline, recoverable world-pack preparation. Not yet a launcher integration.
+
+Uses only stdlib and the project's package validator. Never executes plugin code
+or deletes pack directories. An interrupted metadata commit requires recover.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+from contextlib import contextmanager
+from datetime import datetime, timezone
+import hashlib
+import importlib.util
+import json
+import os
+from pathlib import Path
+import stat
+import sys
+import tempfile
+import uuid
+
+try:
+    import bppack as bp
+except ModuleNotFoundError:
+    # `python -I tools/world_packs.py` intentionally omits the script directory
+    # from sys.path; load the audited sibling explicitly without widening imports.
+    specification = importlib.util.spec_from_file_location(
+        "bedrockplus_world_packs_bppack", Path(__file__).resolve().with_name("bppack.py"))
+    if specification is None or specification.loader is None:
+        raise RuntimeError("Could not load the bundled bppack validator")
+    bp = importlib.util.module_from_spec(specification)
+    sys.modules[specification.name] = bp
+    specification.loader.exec_module(bp)
+
+KINDS = ("behavior", "resource")
+REGISTRATIONS = tuple(f"world_{kind}_packs.json" for kind in KINDS)
+STATE = ".bedrockplus-packs/state.json"
+JOURNAL = ".bedrockplus-packs/pending.json"
+BINDING = ".bedrockplus-packs/binding.json"
+TARGETS = (*REGISTRATIONS, STATE, BINDING)
+MAX_METADATA = 4 * 1024 * 1024
+
+
+def reject(code, message):
+    raise bp.PackValidationError("WORLD_PACK_" + code, message)
+
+
+def safe_path(path: Path) -> Path:
+    path = Path(os.path.abspath(path))
+    if os.name == "nt":
+        import ctypes
+        if len(path.drive) != 2 or path.drive[1] != ":" or ctypes.windll.kernel32.GetDriveTypeW(str(Path(path.anchor))) != 3:
+            reject("PATH", "Use a normal absolute path on a fixed local drive")
+    if any(part.casefold() == "referenceonly" for part in path.parts):
+        reject("REFERENCE", "referenceOnly is permanently read-only")
+    current = Path(path.anchor)
+    for part in path.parts[1:]:
+        if part.endswith((".", " ")) or ":" in part:
+            reject("PATH", "Ambiguous Windows path")
+        current /= part
+        if not os.path.lexists(current):
+            continue
+        info = current.lstat()
+        if stat.S_ISLNK(info.st_mode) or bp._is_reparse_point(info):
+            reject("LINK", f"Links/reparse points are forbidden: {current}")
+        if current != path and not stat.S_ISDIR(info.st_mode):
+            reject("PATH", f"Parent is not a directory: {current}")
+    return path
+
+
+def read_optional(path):
+    safe_path(path)
+    if not os.path.lexists(path):
+        return None
+    return bp._read_verified_installed_file(path, MAX_METADATA)
+
+
+def identifier(value):
+    try:
+        result = str(uuid.UUID(value))
+    except (ValueError, TypeError, AttributeError):
+        reject("UUID", "Pack UUID must be a canonical UUID string")
+    if result != value or result == str(uuid.UUID(int=0)):
+        reject("UUID", "Pack UUID must be canonical lowercase and nonzero")
+    return result
+
+
+def version(value):
+    if not isinstance(value, list) or len(value) != 3 or any(type(n) is not int or not 0 <= n <= 2147483647 for n in value):
+        reject("VERSION", "Pack version must contain three nonnegative integers")
+    return value
+
+
+def pack_manifest(raw, kind):
+    value = bp._decode_json(raw, "vanilla pack manifest")
+    if not isinstance(value, dict) or type(value.get("format_version")) is not int or value["format_version"] != 2:
+        reject("FORMAT", "Only vanilla manifest format 2 is supported")
+    header = value.get("header")
+    modules = value.get("modules")
+    if not isinstance(header, dict) or not isinstance(modules, list) or not 1 <= len(modules) <= 128:
+        reject("MANIFEST", "Pack requires a header and modules")
+    for field in ("name", "description"):
+        if not isinstance(header.get(field), str) or not header[field]:
+            reject("MANIFEST", f"Pack header requires {field}")
+    pack_id = identifier(header.get("uuid"))
+    result = {"pack_id": pack_id, "version": version(header.get("version"))}
+    if version(header.get("min_engine_version")) > [1, 26, 51]:
+        reject("ENGINE", "Pack requires a newer game version than the pinned BDS")
+    if header.get("pack_scope", "world") not in ("world", "any"):
+        reject("SCOPE", "Global-only resource packs cannot be registered to a world")
+    identities = {pack_id}
+    for module in modules:
+        if not isinstance(module, dict) or module.get("type") != {"behavior": "data", "resource": "resources"}[kind]:
+            reject("MODULE", "Initial preparation supports data/resources modules only, not scripts")
+        module_id = identifier(module.get("uuid"))
+        version(module.get("version"))
+        if module_id in identities:
+            reject("UUID_COLLISION", "Header/module UUIDs must be distinct")
+        identities.add(module_id)
+    dependencies = value.get("dependencies", [])
+    if not isinstance(dependencies, list) or len(dependencies) > 128:
+        reject("DEPENDENCY", "Invalid pack dependencies")
+    seen = set()
+    for dependency in dependencies:
+        if not isinstance(dependency, dict) or set(dependency) != {"uuid", "version"}:
+            reject("DEPENDENCY", "Only bundled UUID dependencies are supported")
+        dep_id = identifier(dependency["uuid"])
+        version(dependency["version"])
+        if dep_id in seen or dep_id == pack_id:
+            reject("DEPENDENCY", "Duplicate/self dependency")
+        seen.add(dep_id)
+    return result, sorted(identities), dependencies
+
+
+def registration(raw):
+    entries = [] if raw is None else bp._decode_json(raw, "world pack registrations")
+    if not isinstance(entries, list) or len(entries) > 1024:
+        reject("REGISTRATION", "World registrations must be a bounded array")
+    seen = set()
+    for entry in entries:
+        if not isinstance(entry, dict) or set(entry) != {"pack_id", "version"}:
+            reject("REGISTRATION", "Unsupported existing registration; preserve it manually")
+        key = identifier(entry["pack_id"])
+        version(entry["version"])
+        if key in seen:
+            reject("UUID_COLLISION", "Duplicate world pack UUID")
+        seen.add(key)
+    return entries
+
+
+def encode(raw):
+    return None if raw is None else base64.b64encode(raw).decode("ascii")
+
+
+def decode(value):
+    if value is None:
+        return None
+    if not isinstance(value, str) or len(value) > MAX_METADATA * 2:
+        reject("STATE", "Invalid backup bytes")
+    try:
+        raw = base64.b64decode(value, validate=True)
+    except ValueError:
+        reject("STATE", "Invalid backup encoding")
+    if len(raw) > MAX_METADATA:
+        reject("STATE", "Backup exceeds limit")
+    return raw
+
+
+def plan(world, packages, binding=None):
+    world = safe_path(Path(world))
+    if not world.is_dir() or world == Path(world.anchor):
+        reject("WORLD", "An existing world directory is required")
+    if read_optional(world / JOURNAL) is not None:
+        reject("RECOVERY_REQUIRED", "Recover the pending transaction before preparing or starting BDS")
+    before = {name: read_optional(world / name) for name in TARGETS}
+    if before[STATE] is None and before[BINDING] is not None:
+        reject("STATE", "Pack binding exists without ownership state")
+    baseline = {name: before[name] for name in REGISTRATIONS}
+    if before[STATE] is not None:
+        state = bp._decode_json(before[STATE], "world pack state")
+        if not isinstance(state, dict) or set(state) != {"format", "baseline", "expected", "owned"} or state["format"] != 1:
+            reject("STATE", "Invalid ownership state")
+        if not isinstance(state["baseline"], dict) or not isinstance(state["expected"], dict) or set(state["baseline"]) != set(REGISTRATIONS) or set(state["expected"]) != set(REGISTRATIONS):
+            reject("STATE", "Invalid world metadata state")
+        for name in REGISTRATIONS:
+            if before[name] != decode(state["expected"][name]):
+                reject("CONFLICT", "World registrations were edited outside BedrockPlus; refusing overwrite")
+            baseline[name] = decode(state["baseline"][name])
+    base_entries = {name: registration(raw) for name, raw in baseline.items()}
+    known_ids = {item["pack_id"] for values in base_entries.values() for item in values}
+    owners, packs, package_plugins = set(), [], []
+    if len(packages) > 128:
+        reject("LIMIT", "Too many plugin packages")
+    for package in packages:
+        package = safe_path(Path(package))
+        with bp._open_package_archive(package, bp.DEFAULT_LIMITS) as (archive, info):
+            owner = info.manifest["id"]
+            if owner in owners:
+                reject("OWNER", "Multiple selected versions of one plugin")
+            owners.add(owner)
+            package_plugins.append({"id": owner, "version": info.manifest["version"],
+                                    "sha256": info.result["sha256"]})
+            for declaration in info.manifest.get("packs", []):
+                if len(packs) >= 128:
+                    reject("LIMIT", "Too many bundled packs")
+                kind, root = declaration["type"], declaration["path"]
+                entry = info.entries[root + "/manifest.json"]
+                if entry.file_size > bp.DEFAULT_LIMITS.max_manifest_size:
+                    reject("MANIFEST", "Vanilla pack manifest too large")
+                item, ids, dependencies = pack_manifest(archive.read(entry), kind)
+                if known_ids.intersection(ids):
+                    reject("UUID_COLLISION", "Pack/module UUID conflicts with another pack or an existing registration")
+                known_ids.update(ids)
+                files = {name[len(root) + 1:]: digest for name, digest in info.expected_digests.items() if name.startswith(root + "/")}
+                if any(name.casefold() == "integrity.json" for name in files):
+                    reject("RESERVED_FILE", "Top-level integrity.json inside a vanilla pack is reserved by the snapshot validator")
+                digest = hashlib.sha256(bp._canonical_json(files)).hexdigest()
+                packs.append({**item, "owner": owner, "kind": kind, "source": str(package),
+                              "archive_sha256": info.result["sha256"], "root": root, "files": files,
+                              "target": f"{kind}_packs/bedrockplus_{digest}", "dependencies": dependencies, "identities": ids})
+    by_id = {item["pack_id"]: item for item in packs}
+    by_identity = {key: item for item in packs for key in item["identities"]}
+    # BDS scans installed directories as well as registrations. Refuse duplicate
+    # UUIDs even when an existing copy is not currently registered. In-place
+    # upgrades need a later journalled directory-retirement implementation.
+    if packs:
+        server = world.parent.parent if world.parent.name.casefold() == "worlds" else None
+        scan_roots = [world] + ([server] if server else [])
+        inspected = 0
+        for root in scan_roots:
+            for kind in KINDS:
+                folder = safe_path(root / f"{kind}_packs")
+                if not folder.exists():
+                    continue
+                for child in folder.iterdir():
+                    inspected += 1
+                    if inspected > 4096:
+                        reject("LIMIT", "Too many installed pack folders")
+                    safe_path(child)
+                    if not child.is_dir():
+                        continue
+                    raw = read_optional(child / "manifest.json")
+                    if raw is None:
+                        continue
+                    installed = bp._decode_json(raw, "installed vanilla manifest")
+                    header = installed.get("header", {}) if isinstance(installed, dict) else {}
+                    installed_ids = [header.get("uuid")] if isinstance(header, dict) else []
+                    modules = installed.get("modules", []) if isinstance(installed, dict) else []
+                    if isinstance(modules, list):
+                        installed_ids.extend(module.get("uuid") for module in modules if isinstance(module, dict))
+                    for installed_id in installed_ids:
+                        if isinstance(installed_id, str) and installed_id.lower() in by_identity:
+                            item = by_identity[installed_id.lower()]
+                            if child != world / item["target"]:
+                                reject("INSTALLED_COLLISION", "Pack/module UUID already exists in another installed directory; automatic replacement is not supported")
+    active, visited = set(), set()
+    def visit(item):
+        key = item["pack_id"]
+        if key in active:
+            reject("DEPENDENCY_CYCLE", "Bundled pack dependency cycle")
+        if key in visited:
+            return
+        active.add(key)
+        for dependency in item["dependencies"]:
+            required = by_id.get(dependency["uuid"])
+            if required is None or required["version"] != dependency["version"]:
+                reject("DEPENDENCY", "Pack dependency/version missing from selected bundles")
+            visit(required)
+        active.remove(key)
+        visited.add(key)
+    for item in packs:
+        visit(item)
+    after = {}
+    for kind, name in zip(KINDS, REGISTRATIONS):
+        additions = [{"pack_id": p["pack_id"], "version": p["version"]} for p in packs if p["kind"] == kind]
+        after[name] = bp._canonical_json(base_entries[name] + additions) if additions else baseline[name]
+    after[STATE] = bp._canonical_json({"format": 1, "baseline": {n: encode(baseline[n]) for n in REGISTRATIONS},
+        "expected": {n: encode(after[n]) for n in REGISTRATIONS},
+        "owned": [{k: p[k] for k in ("owner", "kind", "pack_id", "version", "target")} for p in packs]})
+    if binding is None:
+        after[BINDING] = None
+    else:
+        if (not isinstance(binding, dict) or set(binding) != {"set_id", "plugins"} or
+                not isinstance(binding.get("set_id"), str) or not bp.SHA256_RE.fullmatch(binding["set_id"]) or
+                binding.get("plugins") != package_plugins):
+            reject("BINDING", "Invalid prepared plugin-set identity")
+        after[BINDING] = bp._canonical_json({
+            "format": 1,
+            "set_id": binding["set_id"],
+            "plugins": binding["plugins"],
+            "packs": [{k: p[k] for k in ("owner", "archive_sha256", "kind", "root", "pack_id", "version", "target")} for p in packs],
+            "metadata_sha256": {name: None if after[name] is None else hashlib.sha256(after[name]).hexdigest()
+                                for name in (*REGISTRATIONS, STATE)},
+        })
+    # Bound the encoded snapshots too: otherwise a successful write could leave
+    # a journal too large for this same tool to read during recovery.
+    if any(raw is not None and len(raw) > MAX_METADATA for raw in after.values()):
+        reject("LIMIT", "Encoded ownership metadata exceeds the recovery limit")
+    transaction_bytes(before, after)
+    return world, packs, before, after
+
+
+def transaction_bytes(before, after):
+    raw = bp._canonical_json({"format": 1, "before": {n: encode(before[n]) for n in TARGETS},
+                              "after": {n: encode(after[n]) for n in TARGETS}})
+    if len(raw) > MAX_METADATA:
+        reject("LIMIT", "Transaction journal exceeds the recovery limit")
+    return raw
+
+
+@contextmanager
+def offline_world(world, operation="exclusive-access"):
+    # The launcher holds the same lease for its entire run. Directly launched
+    # vanilla BDS does not participate, so --offline is also required.
+    world = safe_path(Path(world))
+    server = world.parent.parent
+    if world.parent.name.casefold() != "worlds" or not world.is_dir() or read_optional(server / "server.properties") is None:
+        reject("WORLD", "Expected an existing <server>/worlds/<world> with server.properties")
+    with bp._cache_install_lease(server):
+        now = datetime.now(timezone.utc)
+        directory = safe_path(world / ".bedrockplus-packs/logs" / now.strftime("%Y-%m-%d"))
+        bp._ensure_private_directory_tree(directory)
+        log_path = directory / f"{now.strftime('%H-%M-%S')}-{uuid.uuid4().hex}.jsonl"
+        with log_path.open("x", encoding="utf-8") as log:
+            def emit(event, **fields):
+                log.write(json.dumps({"timestamp": datetime.now(timezone.utc).isoformat(), "event": event,
+                    "operation": operation, "world": str(world), **fields}) + "\n")
+                log.flush()
+            emit("BPP-WORLD-PACK-BEGIN")
+            try:
+                yield world
+            except Exception as error:
+                emit("BPP-WORLD-PACK-FAILED", code=getattr(error, "code", "WORLD_PACK_IO"), message=str(error))
+                raise
+            else:
+                emit("BPP-WORLD-PACK-COMPLETED")
+
+
+def replace_bytes(path, raw):
+    safe_path(path)
+    read_optional(path)  # reject links, hardlinks, special files before replacing
+    if raw is None:
+        if path.exists():
+            path.unlink()  # exact transaction-owned metadata path, never a tree
+        return
+    bp._ensure_private_directory_tree(path.parent)
+    fd, temporary = tempfile.mkstemp(prefix=".bpp-write-", dir=path.parent)
+    with os.fdopen(fd, "wb") as stream:
+        stream.write(raw)
+        stream.flush()
+        os.fsync(stream.fileno())
+    safe_path(path)
+    os.replace(temporary, path)
+
+
+def stage_pack(world, item):
+    target = safe_path(world / item["target"])
+    if not target.exists():
+        stage_root = bp._ensure_private_directory_tree(world / ".bedrockplus-packs/staging")
+        stage = Path(tempfile.mkdtemp(prefix="pack-", dir=stage_root))
+        with bp._open_package_archive(Path(item["source"]), bp.DEFAULT_LIMITS) as (archive, info):
+            if info.result["sha256"] != item["archive_sha256"]:
+                reject("CHANGED", "Package changed after planning")
+            for relative, digest in item["files"].items():
+                bp._extract_verified_entry(archive, info.entries[item["root"] + "/" + relative], stage / relative, digest)
+        bp._ensure_private_directory_tree(target.parent)
+        stage.rename(target)  # never replace an existing immutable pack directory
+    if any(child.name.casefold() == "integrity.json" for child in target.iterdir()):
+        reject("TAMPERED", "Managed vanilla pack contains a reserved integrity.json entry")
+    files = bp._scan_source(target, bp.DEFAULT_LIMITS)
+    if set(files) != set(item["files"]):
+        reject("TAMPERED", "Managed pack file set differs")
+    for name, source in files.items():
+        if source.path.stat().st_nlink != 1 or bp._hash_source_path(source, bp.DEFAULT_LIMITS.max_file_size) != item["files"][name]:
+            reject("TAMPERED", "Managed pack content differs")
+
+
+def apply(world, packages, *, offline=False, after_replace=None, binding=None):
+    if not offline:
+        reject("OFFLINE_REQUIRED", "Explicit offline acknowledgement required")
+    with offline_world(world, "apply") as world:
+        world, packs, before, after = plan(world, packages, binding=binding)
+        for item in packs:
+            stage_pack(world, item)
+        if any(read_optional(world / name) != before[name] for name in TARGETS):
+            reject("CONFLICT", "World metadata changed while staging")
+        if before == after:
+            return {"status": "unchanged", "packs": len(packs)}
+        replace_bytes(world / JOURNAL, transaction_bytes(before, after))
+        for name in TARGETS:
+            replace_bytes(world / name, after[name])
+            if after_replace:
+                after_replace(name)  # deterministic interruption injection in tests
+        if any(read_optional(world / name) != after[name] for name in TARGETS):
+            reject("CONFLICT", "World metadata changed during commit; recover before launch")
+        (world / JOURNAL).unlink()
+        return {"status": "applied", "packs": len(packs), "retained_pack_directories": True}
+
+
+def selected_world(server, *, allow_missing=False):
+    server = safe_path(Path(server))
+    raw = read_optional(server / "server.properties")
+    if raw is None or len(raw) > 1024 * 1024:
+        reject("SERVER_PROPERTIES", "A bounded server.properties file is required")
+    try:
+        text = raw.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        reject("SERVER_PROPERTIES", "server.properties must be UTF-8")
+    names = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in stripped:
+            continue
+        key, value = stripped.split("=", 1)
+        if key.strip() == "level-name":
+            names.append(value.strip())
+    invalid_name = (len(names) != 1 or not names[0] or len(names[0]) > 255 or
+                    names[0] in (".", "..") or any(c in names[0] for c in '/\\:<>"|?*\0') or
+                    names[0].split(".", 1)[0].casefold() in bp.WINDOWS_RESERVED_NAMES)
+    if invalid_name:
+        reject("LEVEL_NAME", "server.properties must contain one safe level-name")
+    world = safe_path(server / "worlds" / names[0])
+    if world.parent != safe_path(server / "worlds"):
+        reject("WORLD", "The configured world path is invalid")
+    if not world.is_dir():
+        if allow_missing and not os.path.lexists(world):
+            return None
+        reject("WORLD", "The configured world directory does not exist")
+    return world
+
+
+def bind_cache(server, cache, *, offline=False):
+    cache = safe_path(Path(cache))
+    selection_raw = read_optional(cache / "selection.json")
+    if selection_raw is None or len(selection_raw) > 128 * 1024:
+        reject("BINDING", "Prepared plugin set has no bounded selection.json")
+    selection = bp._decode_json(selection_raw, "plugin selection")
+    if (not isinstance(selection, dict) or set(selection) != {"format_version", "plugins"} or
+            selection["format_version"] != 2 or not isinstance(selection["plugins"], list) or
+            len(selection["plugins"]) > 128):
+        reject("BINDING", "Prepared plugin selection has an invalid schema")
+    set_id = hashlib.sha256(selection_raw).hexdigest()
+    if cache.name != set_id:
+        reject("BINDING", "Prepared plugin set path does not match selection identity")
+    plugins, packages, seen = [], [], set()
+    has_packs = False
+    for item in selection["plugins"]:
+        if (not isinstance(item, dict) or set(item) != {"id", "version", "sha256", "package"} or
+                not isinstance(item["id"], str) or not bp.PLUGIN_ID_RE.fullmatch(item["id"]) or
+                bp._plugin_id_uses_reserved_windows_name(item["id"]) or item["id"] in seen or
+                not isinstance(item["version"], str) or not bp.SEMVER_RE.fullmatch(item["version"]) or
+                not isinstance(item["sha256"], str) or not bp.SHA256_RE.fullmatch(item["sha256"]) or
+                not isinstance(item["package"], str) or not item["package"] or
+                Path(item["package"]).name != item["package"]):
+            reject("BINDING", "Prepared plugin selection contains an invalid entry")
+        seen.add(item["id"])
+        package = safe_path(cache / "packages" / f"{item['id']}.bppack")
+        try:
+            validated = bp.validate_package(package)
+        except bp.PackValidationError as error:
+            reject("BINDING", f"Prepared package snapshot is invalid: {error}")
+        if any(validated[key] != item[key] for key in ("id", "version", "sha256")):
+            reject("BINDING", "Prepared package snapshot differs from plugin selection")
+        with bp._open_package_archive(package, bp.DEFAULT_LIMITS) as (_, inspection):
+            has_packs = has_packs or bool(inspection.manifest.get("packs"))
+        plugins.append({key: item[key] for key in ("id", "version", "sha256")})
+        packages.append(package)
+    world = selected_world(server, allow_missing=not has_packs)
+    if world is None:
+        return {"status": "no_bundled_packs", "packs": 0, "set_id": set_id,
+                "world": None, "binding_path": None}
+    result = apply(world, packages if has_packs else [], offline=offline,
+                   binding={"set_id": set_id, "plugins": plugins} if has_packs else None)
+    return {**result, "set_id": set_id, "world": str(world),
+            "binding_path": str(world / BINDING) if has_packs else None}
+
+
+def recover(world, *, offline=False):
+    if not offline:
+        reject("OFFLINE_REQUIRED", "Explicit offline acknowledgement required")
+    with offline_world(world, "recover") as world:
+        raw = read_optional(world / JOURNAL)
+        if raw is None:
+            return {"status": "no_pending_transaction"}
+        journal = bp._decode_json(raw, "pack transaction journal")
+        if not isinstance(journal, dict) or set(journal) != {"format", "before", "after"} or journal["format"] != 1:
+            reject("JOURNAL", "Invalid transaction journal")
+        if any(not isinstance(journal[k], dict) or set(journal[k]) != set(TARGETS) for k in ("before", "after")):
+            reject("JOURNAL", "Invalid transaction targets")
+        before = {n: decode(journal["before"][n]) for n in TARGETS}
+        after = {n: decode(journal["after"][n]) for n in TARGETS}
+        for name in TARGETS:
+            if read_optional(world / name) not in (before[name], after[name]):
+                reject("CONFLICT", "External metadata edit prevents automatic recovery")
+        for name in TARGETS:
+            replace_bytes(world / name, before[name])
+        (world / JOURNAL).unlink()
+        return {"status": "rolled_back", "retained_pack_directories": True}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("operation", choices=("plan", "apply", "recover", "bind"))
+    parser.add_argument("world", type=Path)
+    parser.add_argument("packages", type=Path, nargs="*")
+    parser.add_argument("--offline", action="store_true", help="I have stopped BDS and will not start it during this operation")
+    args = parser.parse_args()
+    try:
+        if args.operation == "plan":
+            _, packs, _, _ = plan(args.world, args.packages)
+            result = {"status": "planned", "packs": [{k: p[k] for k in ("owner", "kind", "pack_id", "version", "target")} for p in packs]}
+        elif args.operation == "apply":
+            result = apply(args.world, args.packages, offline=args.offline)
+        elif args.operation == "recover":
+            if args.packages:
+                parser.error("recover does not accept packages")
+            result = recover(args.world, offline=args.offline)
+        else:
+            if len(args.packages) != 1:
+                parser.error("bind requires exactly one prepared plugin-set cache")
+            result = bind_cache(args.world, args.packages[0], offline=args.offline)
+        print(json.dumps(result))
+        return 0
+    except (bp.PackValidationError, OSError) as error:
+        print(json.dumps({"status": "error", "code": getattr(error, "code", "WORLD_PACK_IO"), "message": str(error)}), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bedrockplus/api.py

@@ -0,0 +1,83 @@
+"""Protocols implemented by the BedrockPlus embedded plugin host."""
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Protocol, TypeAlias
+
+from .commands import CommandCallback, CommandOverload
+from .events import Event, EventName, EventPriority
+
+TaskCallback: TypeAlias = Callable[[], None]
+EventCallback: TypeAlias = Callable[[Event], None]
+
+
+class PluginHost(Protocol):
+    """The object supplied to ``Plugin.on_load``."""
+
+    def log(
+        self,
+        level: str,
+        event_code: str,
+        message: str,
+        fields: Mapping[str, str] | None = None,
+    ) -> None: ...
+
+    def data_directory(self) -> str: ...
+
+    def scheduler_available(self) -> bool: ...
+
+    def schedule(
+        self,
+        callback: TaskCallback,
+        delay_ms: int = 0,
+        interval_ms: int = 0,
+        runs: int = 1,
+    ) -> int: ...
+
+    def cancel_task(self, task_id: int) -> bool: ...
+
+    def events_available(self) -> bool: ...
+
+    def subscribe_event(
+        self,
+        name: EventName,
+        callback: EventCallback,
+        priority: EventPriority | int = EventPriority.NORMAL,
+    ) -> int: ...
+
+    def unsubscribe_event(self, subscription_id: int) -> bool: ...
+
+    def commands_available(self) -> bool: ...
+
+    def register_command(
+        self,
+        name: str,
+        callback: CommandCallback,
+        description: str = "",
+        permission: str = "",
+        aliases: Sequence[str] | None = None,
+        overloads: Sequence[CommandOverload] | None = None,
+    ) -> None: ...
+
+    def unregister_command(self, name: str) -> bool: ...
+
+    def dispatch_server_command(self, command: str) -> bool: ...
+
+    def hide_vanilla_command(self, name: str) -> bool: ...
+
+    def restore_vanilla_command(self, name: str) -> bool: ...
+
+
+class Plugin(Protocol):
+    """Lifecycle surface expected from a Python plugin entry class."""
+
+    def on_load(self, host: PluginHost) -> None: ...
+
+    def on_enable(self) -> None: ...
+
+    def on_server_ready(self) -> None: ...
+
+    def on_server_stopping(self) -> None: ...
+
+    def on_disable(self) -> None: ...
+
+    def on_unload(self) -> None: ...