ghostbt 0.1.0__py3-none-any.whl

ghostbt/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ghostbt/__main__.py

@@ -0,0 +1,4 @@
+import sys
+from .cli import main
+
+sys.exit(main())

ghostbt/build.py

@@ -0,0 +1,41 @@
+import pathlib
+import subprocess
+import sys
+
+from .config import load_manifest, detect_target
+from .esp_idf import idf_command
+
+
+def build_app(
+    app_dir: str = ".",
+    target: str = None,
+    skip_set_target: bool = False,
+) -> pathlib.Path:
+    app_path = pathlib.Path(app_dir).resolve()
+    if not (app_path / "CMakeLists.txt").exists():
+        print(f"not an app project: {app_path}", file=sys.stderr)
+        raise SystemExit(2)
+
+    if target is None:
+        try:
+            manifest = load_manifest(app_path)
+            target = detect_target(manifest)
+        except (FileNotFoundError, ValueError):
+            target = "esp32s3"
+
+    if not skip_set_target:
+        cmd, env = idf_command("set-target", target)
+        subprocess.check_call(cmd, cwd=app_path, env=env)
+    cmd, env = idf_command("build")
+    subprocess.check_call(cmd, cwd=app_path, env=env)
+
+    try:
+        manifest = load_manifest(app_path)
+        so_path = app_path / "build" / manifest["entry"]
+        if so_path.exists():
+            print(so_path)
+            return so_path
+    except (FileNotFoundError, ValueError):
+        pass
+
+    return app_path / "build"

ghostbt/cli.py

@@ -0,0 +1,171 @@
+import argparse
+import sys
+
+from . import __version__
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="gbt",
+        description="Ghost Build Tool - build and package GhostESP native SD apps",
+    )
+    parser.add_argument("--version", action="version", version=f"gbt {__version__}")
+    parser.add_argument("-v", "--verbose", action="store_true")
+
+    sub = parser.add_subparsers(dest="command")
+
+    p_create = sub.add_parser("create", help="Scaffold a new app from template")
+    p_create.add_argument("app_id", help="Safe app id, e.g. my_tool")
+    p_create.add_argument("--name", help="Display name (default: title-cased app_id)")
+    p_create.add_argument("--template", default="basic_app", help="Template name under plugins/templates/")
+    p_create.add_argument("--out", default=".", help="Output parent directory (default: current dir)")
+
+    p_build = sub.add_parser("build", help="Build an app project")
+    p_build.add_argument("app_dir", nargs="?", default=".", help="App project directory (default: .)")
+    p_build.add_argument("--target", default=None, help="ESP-IDF target (default: from manifest or esp32s3)")
+    p_build.add_argument("--skip-set-target", action="store_true", help="Skip idf.py set-target step")
+
+    p_package = sub.add_parser("package", help="Package a built app")
+    p_package.add_argument("app_dir", nargs="?", default=".", help="App project directory (default: .)")
+    p_package.add_argument("--out", default=None, help="Output dist directory")
+    p_package.add_argument("--gapp", action="store_true", help="Also create a .gapp archive")
+
+    p_dist = sub.add_parser("dist", help="Build and package in one step")
+    p_dist.add_argument("app_dir", nargs="?", default=".", help="App project directory (default: .)")
+    p_dist.add_argument("--target", default=None, help="ESP-IDF target (default: from manifest or esp32s3)")
+    p_dist.add_argument("--out", default=None, help="Output dist directory")
+    p_dist.add_argument("--gapp", action="store_true", help="Also create a .gapp archive")
+
+    p_setup = sub.add_parser("setup", help="Install or configure ESP-IDF toolchain")
+    p_setup.add_argument("--target", nargs="+", default=["esp32s3"], help="ESP-IDF targets to install (default: esp32s3)")
+    p_setup.add_argument("--idf-version", default=None, help="ESP-IDF version (default: v6.0.1)")
+    p_setup.add_argument("--install-dir", default=None, help="Custom install directory (default: ~/.ghostbt/esp-idf)")
+
+    p_boards = sub.add_parser("boards", help="List available firmware board configs")
+
+    p_fw = sub.add_parser("firmware", help="Build GhostESP firmware for a board")
+    p_fw.add_argument("board", help="Board config name (e.g. cardputer, ghostboard). Use 'gbt boards' to list.")
+    p_fw.add_argument("--repo", default=None, help="Path to GhostESP repo (default: auto-detect)")
+    p_fw.add_argument("--skip-set-target", action="store_true", help="Skip idf.py set-target step")
+
+    p_flash = sub.add_parser("flash", help="Flash firmware or app to device")
+    p_flash.add_argument("target", nargs="?", default="firmware", choices=["firmware", "app"],
+                         help="What to flash: firmware (default) or app")
+    p_flash.add_argument("--port", "-p", default=None, help="Serial port (auto-detected if omitted)")
+    p_flash.add_argument("--baud", "-b", type=int, default=None, help="Baud rate (default: 460800)")
+    p_flash.add_argument("--board", default=None, help="Board config (builds firmware if needed)")
+    p_flash.add_argument("--app-dir", default=None, help="App directory (for 'app' target)")
+    p_flash.add_argument("--build-dir", default=None, help="Custom build directory")
+    p_flash.add_argument("--verify", action="store_true", help="Verify after writing")
+    p_flash.add_argument("--erase", action="store_true", help="Erase entire flash before writing")
+    p_flash.add_argument("--monitor", "-m", action="store_true", help="Open serial monitor after flashing")
+
+    p_mon = sub.add_parser("monitor", help="Open serial monitor")
+    p_mon.add_argument("--port", "-p", default=None, help="Serial port (auto-detected if omitted)")
+    p_mon.add_argument("--baud", "-b", type=int, default=115200, help="Baud rate (default: 115200)")
+
+    p_ports = sub.add_parser("ports", help="List available serial ports")
+
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    if args.command == "create":
+        from .create import create_app
+        create_app(
+            app_id=args.app_id,
+            name=args.name,
+            template=args.template,
+            out_dir=args.out,
+        )
+    elif args.command == "build":
+        from .build import build_app
+        build_app(
+            app_dir=args.app_dir,
+            target=args.target,
+            skip_set_target=args.skip_set_target,
+        )
+    elif args.command == "package":
+        from .package import package_app
+        package_app(
+            app_dir=args.app_dir,
+            out=args.out,
+            make_gapp=args.gapp,
+        )
+    elif args.command == "dist":
+        from .dist import dist_app
+        dist_app(
+            app_dir=args.app_dir,
+            target=args.target,
+            out=args.out,
+            make_gapp=args.gapp,
+        )
+    elif args.command == "setup":
+        from .esp_idf import setup_idf
+        setup_idf(
+            targets=args.target,
+            idf_version=args.idf_version,
+            install_dir=args.install_dir,
+        )
+    elif args.command == "boards":
+        from .firmware import list_boards
+        boards = list_boards()
+        if not boards:
+            print("No board configs found. Run from inside the GhostESP repo.")
+            return 1
+        print(f"{'Board':<30} {'Target':<12}")
+        print("-" * 42)
+        for b in boards:
+            print(f"{b['id']:<30} {b['target']:<12}")
+        print(f"\n{len(boards)} boards available")
+    elif args.command == "firmware":
+        from .firmware import build_firmware
+        build_firmware(
+            board=args.board,
+            repo_root=args.repo,
+            skip_set_target=args.skip_set_target,
+        )
+    elif args.command == "flash":
+        from .flash import flash_firmware, flash_app, monitor
+        if args.target == "app":
+            if not args.app_dir:
+                print("--app-dir is required for 'app' target", file=sys.stderr)
+                return 2
+            used_port = flash_app(
+                app_dir=args.app_dir,
+                port=args.port,
+                baud=args.baud,
+            )
+        else:
+            used_port = flash_firmware(
+                port=args.port,
+                baud=args.baud,
+                board=args.board,
+                build_dir=args.build_dir,
+                verify=args.verify,
+                erase_flash=args.erase,
+            )
+        if args.monitor and used_port:
+            monitor(port=used_port)
+    elif args.command == "monitor":
+        from .flash import monitor
+        monitor(port=args.port, baud=args.baud)
+    elif args.command == "ports":
+        from .flash import list_serial_ports
+        ports = list_serial_ports()
+        if not ports:
+            print("No serial ports found.")
+            return 1
+        print(f"{'Port':<20} {'Description'}")
+        print("-" * 60)
+        for p in ports:
+            print(f"{p['device']:<20} {p['description']}")
+        print(f"\n{len(ports)} port(s) available")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ghostbt/config.py

@@ -0,0 +1,92 @@
+import json
+import os
+import pathlib
+import shutil
+
+
+REPO_MARKERS = ["plugins", "main", "components"]
+SDK_RELATIVE = pathlib.Path("plugins") / "sdk"
+TEMPLATES_RELATIVE = pathlib.Path("plugins") / "templates"
+
+
+def _data_root() -> pathlib.Path:
+    here = pathlib.Path(__file__).resolve().parent
+    return here / "data"
+
+
+def find_repo_root(start: pathlib.Path = None) -> pathlib.Path:
+    env = os.environ.get("GHOSTBT_ROOT")
+    if env:
+        p = pathlib.Path(env)
+        if all((p / m).is_dir() for m in REPO_MARKERS):
+            return p
+    cur = (start or pathlib.Path.cwd()).resolve()
+    for _ in range(20):
+        if all((cur / m).is_dir() for m in REPO_MARKERS):
+            return cur
+        parent = cur.parent
+        if parent == cur:
+            break
+        cur = parent
+    raise FileNotFoundError(
+        "Cannot find GhostESP repo root. Run from inside the repo or set GHOSTBT_ROOT."
+    )
+
+
+def resolve_sdk_path(start: pathlib.Path = None) -> pathlib.Path:
+    env = os.environ.get("GHOSTBT_SDK")
+    if env:
+        p = pathlib.Path(env)
+        if p.is_file():
+            return p
+    try:
+        root = find_repo_root(start)
+        sdk = root / SDK_RELATIVE / "ghostesp_plugin_api.h"
+        if sdk.is_file():
+            return sdk
+    except FileNotFoundError:
+        pass
+    bundled = _data_root() / "sdk" / "ghostesp_plugin_api.h"
+    if bundled.is_file():
+        return bundled
+    raise FileNotFoundError(
+        "SDK header not found. Set GHOSTBT_SDK environment variable, run from a GhostESP repo, or reinstall ghostbt."
+    )
+
+
+def resolve_template(name: str, start: pathlib.Path = None) -> pathlib.Path:
+    try:
+        repo = find_repo_root(start)
+        tpl = repo / TEMPLATES_RELATIVE / name
+        if tpl.is_dir():
+            return tpl
+    except FileNotFoundError:
+        pass
+    bundled = _data_root() / "templates" / name
+    if bundled.is_dir():
+        return bundled
+    raise FileNotFoundError(f"Template not found: {name}")
+
+
+def copy_bundled_sdk(dst_dir: pathlib.Path) -> pathlib.Path:
+    dst = dst_dir / "sdk" / "ghostesp_plugin_api.h"
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    src = resolve_sdk_path()
+    if not dst.exists() or src.stat().st_mtime > dst.stat().st_mtime:
+        shutil.copy2(src, dst)
+    return dst
+
+
+def load_manifest(app_dir: pathlib.Path) -> dict:
+    manifest_path = app_dir / "manifest.json"
+    if not manifest_path.is_file():
+        raise FileNotFoundError(f"manifest.json not found in {app_dir}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    for field in ("id", "entry"):
+        if field not in manifest:
+            raise ValueError(f"manifest.json missing required field: {field}")
+    return manifest
+
+
+def detect_target(manifest: dict) -> str:
+    return manifest.get("target", "esp32s3")

ghostbt/create.py

@@ -0,0 +1,54 @@
+import pathlib
+import shutil
+import sys
+
+from .config import resolve_template, copy_bundled_sdk
+
+
+def _render_file(path: pathlib.Path, values: dict) -> None:
+    text = path.read_text(encoding="utf-8")
+    for key, value in values.items():
+        text = text.replace("{{" + key + "}}", value)
+    path.write_text(text, encoding="utf-8")
+
+
+def create_app(
+    app_id: str,
+    name: str = None,
+    template: str = "basic_app",
+    out_dir: str = ".",
+) -> pathlib.Path:
+    if not app_id.replace("_", "").replace("-", "").isalnum():
+        print("app_id may only contain letters, numbers, _ and -", file=sys.stderr)
+        raise SystemExit(2)
+
+    src = resolve_template(template)
+    out_parent = pathlib.Path(out_dir).resolve()
+    dst = out_parent / app_id
+    if dst.exists():
+        print(f"destination already exists: {dst}", file=sys.stderr)
+        raise SystemExit(2)
+
+    shutil.copytree(src, dst)
+    copy_bundled_sdk(dst)
+
+    symbol = app_id.replace("-", "_")
+    display_name = name or app_id.replace("_", " ").replace("-", " ").title()
+
+    values = {
+        "APP_ID": app_id,
+        "APP_NAME": display_name,
+        "APP_SYMBOL": symbol,
+    }
+
+    for path in sorted(dst.rglob("*"), key=lambda p: len(p.parts), reverse=True):
+        if "{{APP_SYMBOL}}" in path.name:
+            path = path.rename(path.with_name(path.name.replace("{{APP_SYMBOL}}", symbol)))
+        if path.is_file() and (
+            path.suffix in {".c", ".h", ".json", ".txt", ".cmake", ".yml"}
+            or path.name == "CMakeLists.txt"
+        ):
+            _render_file(path, values)
+
+    print(dst)
+    return dst