forkbit-sdk 0.1.0__py3-none-any.whl

forkbit_sdk/__init__.py

@@ -0,0 +1,5 @@
+from forkbit_sdk.base_plugin import BasePlugin
+from forkbit_sdk.git_client import GitClient, GitError
+
+__all__ = ["BasePlugin", "GitClient", "GitError"]
+__version__ = "0.1.0"

forkbit_sdk/base_plugin.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import io
+import json
+import logging
+from pathlib import Path
+from typing import Callable
+
+from PySide6.QtWidgets import QWidget
+
+from forkbit_sdk.git_client import GitClient
+
+log = logging.getLogger(__name__)
+
+
+class BasePlugin:
+    """Base class for all ForkBit plugins.
+
+    Subclass this and override :meth:`on_ready` to build your plugin UI.
+    The app creates an instance, injects context (project, settings, git),
+    and calls ``on_ready()`` when everything is wired up.
+
+    Example::
+
+        from forkbit_sdk import BasePlugin
+        from PySide6.QtWidgets import QLabel, QVBoxLayout
+
+        class MyPlugin(BasePlugin):
+            def on_ready(self):
+                layout = QVBoxLayout(self.container)
+                layout.addWidget(QLabel("Hello!"))
+    """
+
+    def __init__(self):
+        self.container = QWidget()
+        """The root widget for your plugin UI. Build your layout inside this."""
+        self.container.setObjectName("pluginContainer")
+        self.git = GitClient()
+        """Git operations for the current project. See :class:`GitClient`."""
+        self._settings: dict = {}
+        self._project_id: str = ""
+        self._project_path: str = ""
+        self._plugin_id: str = ""
+        self._version: str = ""
+        self._plugin_name: str = ""
+        self._plugin_subtitle: str = ""
+        self._plugin_icon: str = ""
+        self._plugin_icon_colors: tuple[str, str] = ("", "")
+        self._plugin_icon_path: str = ""
+        self._data_dir: Path | None = None
+        self._notify_fn: Callable[[str, str], None] | None = None
+        self._subtitle_changed_fn: Callable[[str], None] | None = None
+        self._translate_fn: Callable[
+            [str, str, str, Callable[[str], None] | None, Callable[[str], None] | None],
+            str,
+        ] | None = None
+        self._status_chip: QWidget | None = None
+
+    @property
+    def plugin_id(self) -> str:
+        """The unique plugin identifier (e.g. ``com.mycompany.myplugin``)."""
+        return self._plugin_id
+
+    @property
+    def version(self) -> str:
+        """The plugin version from ``plugin.json``."""
+        return self._version
+
+    @property
+    def plugin_name(self) -> str:
+        """The display name shown in the sidebar."""
+        return self._plugin_name
+
+    @property
+    def plugin_subtitle(self) -> str:
+        """The subtitle shown below the plugin name in the header."""
+        return self._plugin_subtitle
+
+    @property
+    def plugin_icon(self) -> str:
+        """The icon name (Lucide icon ID) for this plugin."""
+        return self._plugin_icon
+
+    @property
+    def plugin_icon_colors(self) -> tuple[str, str]:
+        """Gradient colors ``(start, end)`` for the plugin icon background."""
+        return self._plugin_icon_colors
+
+    @property
+    def plugin_icon_path(self) -> str:
+        """Path to a custom icon file, if set."""
+        return self._plugin_icon_path
+
+    @property
+    def data_dir(self) -> Path:
+        """Per-instance directory for plugin file storage.
+
+        Created automatically by the app before :meth:`on_ready` is called.
+        Use :meth:`read_json` and :meth:`write_json` for convenient access.
+
+        :raises RuntimeError: If accessed before ``on_ready()``.
+        """
+        if self._data_dir is None:
+            raise RuntimeError("data_dir is not available before on_ready()")
+        return self._data_dir
+
+    def read_json(self, filename: str) -> dict:
+        """Read a JSON file from :attr:`data_dir`.
+
+        :param filename: Name of the JSON file (e.g. ``"state.json"``).
+        :returns: Parsed dict, or empty dict if the file doesn't exist.
+        """
+        path = self.data_dir / filename
+        if not path.exists():
+            return {}
+        return json.loads(path.read_text(encoding="utf-8"))
+
+    def write_json(self, filename: str, data: dict) -> None:
+        """Atomic-write a JSON file to :attr:`data_dir`.
+
+        Writes to a temporary file first, then renames — safe against crashes.
+
+        :param filename: Name of the JSON file (e.g. ``"state.json"``).
+        :param data: The dict to serialize.
+        """
+        path = self.data_dir / filename
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        tmp.replace(path)
+
+    @property
+    def settings(self) -> dict:
+        """Current plugin settings values as defined in ``settings.json``."""
+        return self._settings
+
+    def secret_file(self, field_id: str) -> bytes:
+        """Return the raw bytes for a ``secret_file`` settings field.
+
+        :param field_id: The field ID from ``settings.json``.
+        :returns: Raw file content as bytes.
+        :raises KeyError: If no secret file is loaded for the given field.
+        """
+        value = self._settings.get(field_id)
+        if not isinstance(value, bytes):
+            raise KeyError(f"No secret file loaded for '{field_id}'")
+        return value
+
+    def secret_file_stream(self, field_id: str) -> io.BytesIO:
+        """Return a file-like ``BytesIO`` for a ``secret_file`` settings field.
+
+        Useful when a library expects a file object instead of raw bytes.
+
+        :param field_id: The field ID from ``settings.json``.
+        :returns: A seekable ``BytesIO`` stream.
+        """
+        return io.BytesIO(self.secret_file(field_id))
+
+    @property
+    def project_id(self) -> str:
+        """The unique ID of the currently open project."""
+        return self._project_id
+
+    @property
+    def project_path(self) -> str:
+        """Filesystem path to the project directory."""
+        return self._project_path
+
+    def on_ready(self) -> None:
+        """Called when the plugin is fully initialized.
+
+        Override this to build your UI inside :attr:`container` and set up
+        initial state. All context properties (:attr:`settings`, :attr:`data_dir`,
+        :attr:`git`, etc.) are available at this point.
+        """
+        pass
+
+    def on_settings_changed(self, settings: dict) -> None:
+        """Called when the user saves plugin settings.
+
+        Override this to react to settings changes at runtime (e.g. refresh
+        data with a new API key). The base implementation updates
+        :attr:`settings` — call ``super()`` if you override.
+
+        :param settings: The full updated settings dict.
+        """
+        self._settings = settings
+
+    @property
+    def status_chip(self) -> QWidget | None:
+        """Optional status chip widget in the plugin header.
+
+        Injected by the app — ``None`` until :meth:`on_ready` runs.
+        """
+        return self._status_chip
+
+    def set_subtitle(self, text: str) -> None:
+        """Update the subtitle shown in the plugin header.
+
+        :param text: New subtitle text (e.g. ``"v1.2.0 — 3 locales"``).
+        """
+        self._plugin_subtitle = text
+        if self._subtitle_changed_fn:
+            self._subtitle_changed_fn(text)
+
+    def notify(self, message: str, level: str = "info") -> None:
+        """Show a toast notification to the user.
+
+        :param message: The notification text.
+        :param level: One of ``"info"``, ``"success"``, ``"warning"``, ``"error"``.
+        """
+        if self._notify_fn:
+            self._notify_fn(message, level)
+        else:
+            log.info("[%s] %s: %s", self._plugin_id, level, message)
+
+    def translate(
+        self,
+        text: str,
+        source_lang: str,
+        target_lang: str,
+        on_done: Callable[[str], None] | None = None,
+        on_error: Callable[[str], None] | None = None,
+    ) -> str:
+        """Request an asynchronous translation via the app's translation service.
+
+        The translation runs in a background thread. Results arrive via callbacks.
+
+        :param text: The text to translate.
+        :param source_lang: Source language code (e.g. ``"en"``).
+        :param target_lang: Target language code (e.g. ``"de"``).
+        :param on_done: Callback receiving the translated text.
+        :param on_error: Callback receiving an error message.
+        :returns: A request ID for tracking.
+        :raises RuntimeError: If no translation service is configured.
+        """
+        if self._translate_fn:
+            return self._translate_fn(text, source_lang, target_lang, on_done, on_error)
+        raise RuntimeError("Translation service is not available")

forkbit_sdk/cli.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from forkbit_sdk import __version__
+from forkbit_sdk.commands import build, init_plugin, release, validate
+
+_COMMANDS = {
+    "init": init_plugin,
+    "validate": validate,
+    "build": build,
+    "release": release,
+}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="forkbit", description="ForkBit Plugin SDK")
+    parser.add_argument("--version", action="version", version=f"forkbit-sdk {__version__}")
+
+    sub = parser.add_subparsers(dest="command")
+    plugin_parser = sub.add_parser("plugin", help="Plugin authoring tools")
+    plugin_sub = plugin_parser.add_subparsers(dest="action")
+
+    for cmd in _COMMANDS.values():
+        cmd.register(plugin_sub)
+
+    args = parser.parse_args()
+
+    if args.command == "plugin":
+        if args.action is None:
+            plugin_parser.print_help()
+            sys.exit(1)
+        cmd = _COMMANDS[args.action]
+        sys.exit(cmd.run(args))
+
+    parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

forkbit_sdk/commands/_shared.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+PLATFORM_TAGS = {
+    ("darwin", "arm64"): "macos_arm64",
+    ("darwin", "x86_64"): "macos_x86_64",
+    ("win32", "AMD64"): "windows_x86_64",
+    ("linux", "x86_64"): "linux_x86_64",
+}
+
+ALL_PLATFORMS = ["macos_arm64", "macos_x86_64", "windows_x86_64", "linux_x86_64"]
+
+PIP_PLATFORM_MAP = {
+    "macos_arm64": "macosx_11_0_arm64",
+    "macos_x86_64": "macosx_11_0_x86_64",
+    "windows_x86_64": "win_amd64",
+    "linux_x86_64": "manylinux2014_x86_64",
+}
+
+
+def current_platform_tag() -> str:
+    return PLATFORM_TAGS.get((sys.platform, platform.machine()), "")
+
+
+def python_version_tag() -> str:
+    return f"{sys.version_info.major}{sys.version_info.minor}"
+
+
+def is_pure_wheel(whl_path: Path) -> bool:
+    return "-none-any.whl" in whl_path.name
+
+
+def unpack_wheel(whl_path: Path, dest: Path) -> None:
+    with zipfile.ZipFile(whl_path, "r") as zf:
+        for info in zf.infolist():
+            if info.filename.endswith(".dist-info/") or ".dist-info/" in info.filename:
+                continue
+            zf.extract(info, dest)
+
+
+def download_for_current_platform(
+    requirements: list[str],
+    vendor_dir: Path,
+    platform_tag: str,
+) -> bool:
+    tmp = vendor_dir / "_download"
+    tmp.mkdir(parents=True, exist_ok=True)
+
+    print(f"  Resolving {', '.join(requirements)} ...")
+    result = subprocess.run(
+        [
+            sys.executable, "-m", "pip", "download",
+            *requirements,
+            "--dest", str(tmp),
+            "--only-binary=:all:",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        last_line = stderr.splitlines()[-1] if stderr else "unknown error"
+        print(f"  ✗ Failed to download dependencies for {platform_tag}:")
+        print(f"    {last_line}")
+        shutil.rmtree(tmp, ignore_errors=True)
+        return False
+
+    _sort_wheels(tmp, vendor_dir, platform_tag)
+    shutil.rmtree(tmp, ignore_errors=True)
+    return True
+
+
+def download_for_platform(
+    requirements: list[str],
+    vendor_dir: Path,
+    platform_tag: str,
+) -> bool:
+    pip_platform = PIP_PLATFORM_MAP.get(platform_tag)
+    if not pip_platform:
+        print(f"  ✗ Unknown platform: {platform_tag}")
+        return False
+
+    tmp = vendor_dir / f"_download_{platform_tag}"
+    tmp.mkdir(parents=True, exist_ok=True)
+
+    py_ver = python_version_tag()
+
+    result = subprocess.run(
+        [
+            sys.executable, "-m", "pip", "download",
+            *requirements,
+            "--dest", str(tmp),
+            "--only-binary=:all:",
+            "--platform", pip_platform,
+            "--python-version", py_ver,
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        last_line = stderr.splitlines()[-1] if stderr else "unknown error"
+        print(f"  ✗ Failed to download dependencies for {platform_tag}:")
+        print(f"    {last_line}")
+        shutil.rmtree(tmp, ignore_errors=True)
+        return False
+
+    _sort_wheels(tmp, vendor_dir, platform_tag)
+    shutil.rmtree(tmp, ignore_errors=True)
+    return True
+
+
+def _sort_wheels(download_dir: Path, vendor_dir: Path, platform_tag: str) -> None:
+    common_dir = vendor_dir / "common"
+    plat_dir = vendor_dir / platform_tag
+
+    for whl in download_dir.glob("*.whl"):
+        if is_pure_wheel(whl):
+            dest = common_dir
+        else:
+            dest = plat_dir
+        dest.mkdir(parents=True, exist_ok=True)
+        unpack_wheel(whl, dest)
+
+
+def copy_plugin_source(plugin_dir: Path, build_dir: Path) -> None:
+    for item in plugin_dir.iterdir():
+        if item.name.startswith("_") or item.name.startswith("."):
+            continue
+        if item.suffix == ".forkbit":
+            continue
+        if item.is_file():
+            shutil.copy2(item, build_dir / item.name)
+        elif item.is_dir() and item.name != "vendor":
+            shutil.copytree(item, build_dir / item.name)
+
+
+def compile_pyc(build_dir: Path) -> None:
+    import compileall
+    import py_compile
+
+    compileall.compile_dir(
+        str(build_dir),
+        quiet=1,
+        legacy=True,
+    )
+
+    for py_file in list(build_dir.rglob("*.py")):
+        pyc_file = py_file.with_suffix(".pyc")
+        if not pyc_file.exists():
+            try:
+                py_compile.compile(str(py_file), cfile=str(pyc_file), doraise=True)
+            except py_compile.PyCompileError:
+                continue
+        py_file.unlink()
+
+
+def create_zip(plugin_dir: Path, build_dir: Path, manifest: dict) -> Path:
+    plugin_id = manifest["id"]
+    version = manifest["version"]
+    output_name = f"{plugin_id}-{version}.forkbit"
+    output_path = plugin_dir / output_name
+
+    with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for file_path in sorted(build_dir.rglob("*")):
+            if file_path.is_file():
+                arcname = file_path.relative_to(build_dir)
+                zf.write(file_path, arcname)
+
+    return output_path
+
+
+def format_size(size_bytes: int) -> str:
+    size_kb = size_bytes / 1024
+    if size_kb > 1024:
+        return f"{size_kb / 1024:.1f} MB"
+    return f"{size_kb:.0f} KB"

forkbit_sdk/commands/build.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+from forkbit_sdk.commands import validate
+from forkbit_sdk.commands._shared import (
+    copy_plugin_source,
+    create_zip,
+    current_platform_tag,
+    download_for_current_platform,
+    format_size,
+)
+
+
+def run(args) -> int:
+    plugin_dir = Path(args.dir).resolve()
+
+    print(f"Building plugin in {plugin_dir}/\n")
+    print("Running validation...")
+
+    result = validate._Result()
+    manifest = validate._check_manifest(plugin_dir, result)
+    if manifest:
+        validate._check_entry_point(plugin_dir, manifest, result)
+        validate._check_imports(plugin_dir, manifest, result)
+
+    if not result.success:
+        print()
+        result.print()
+        print(f"\nBuild aborted: {len(result.failed)} validation error(s).")
+        return 1
+
+    print(f"  ✓ All {len(result.passed)} checks passed\n")
+
+    platform_tag = current_platform_tag()
+    if not platform_tag:
+        print(f"  ✗ Unsupported platform: {sys.platform}/{platform.machine()}")
+        return 1
+
+    for old in plugin_dir.glob("*.forkbit"):
+        old.unlink()
+
+    build_dir = plugin_dir / "_build"
+    if build_dir.exists():
+        shutil.rmtree(build_dir)
+    build_dir.mkdir()
+
+    copy_plugin_source(plugin_dir, build_dir)
+
+    requirements = manifest.get("requirements", [])
+    if requirements:
+        print(f"Vendoring dependencies for {platform_tag}...")
+        vendor_dir = build_dir / "vendor"
+        if not download_for_current_platform(requirements, vendor_dir, platform_tag):
+            shutil.rmtree(build_dir, ignore_errors=True)
+            return 1
+        print(f"  ✓ Dependencies vendored\n")
+
+    output_path = create_zip(plugin_dir, build_dir, manifest)
+    shutil.rmtree(build_dir, ignore_errors=True)
+
+    print(f"Built: {output_path.name} ({format_size(output_path.stat().st_size)})")
+    print(f"Platform: {platform_tag}")
+    return 0
+
+
+def register(subparsers) -> None:
+    p = subparsers.add_parser("build", help="Build plugin for current platform (dev)")
+    p.add_argument("dir", nargs="?", default=".", help="Plugin directory to build")

forkbit_sdk/commands/init_plugin.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+_ID_PATTERN = re.compile(r"^com\.[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$")
+
+
+def _prompt(label: str, default: str = "") -> str:
+    suffix = f" [{default}]" if default else ""
+    value = input(f"{label}{suffix}: ").strip()
+    return value or default
+
+
+def _to_class_name(name: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9]", "", name.title()) + "Plugin"
+
+
+def _generate_manifest(plugin_id: str, name: str, description: str) -> str:
+    data = {
+        "id": plugin_id,
+        "name": name,
+        "version": "0.1.0",
+        "description": description,
+        "entry": "main.py",
+        "min_app_version": "0.2.0",
+        "requirements": [],
+    }
+    return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+def _generate_main(name: str) -> str:
+    cls = _to_class_name(name)
+    return f'''\
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QLabel, QVBoxLayout
+
+from forkbit_sdk import BasePlugin
+
+
+class {cls}(BasePlugin):
+
+    def on_ready(self) -> None:
+        layout = QVBoxLayout(self.container)
+        layout.setAlignment(Qt.AlignmentFlag.AlignTop)
+
+        status = QLabel("Plugin loaded successfully.")
+        layout.addWidget(status)
+'''
+
+
+def _generate_settings() -> str:
+    return json.dumps({"fields": []}, indent=2, ensure_ascii=False)
+
+
+def run(args) -> int:
+    target = Path(args.dir)
+
+    if not args.non_interactive:
+        print("ForkBit Plugin Scaffold\n")
+        plugin_id = _prompt("Plugin ID (com.<vendor>.<name>)", "")
+        name = _prompt("Display name", "")
+        description = _prompt("Description", "")
+    else:
+        plugin_id = args.id or ""
+        name = args.name or ""
+        description = args.description or ""
+
+    if not plugin_id:
+        print("Error: Plugin ID is required.", file=sys.stderr)
+        return 1
+    if not _ID_PATTERN.match(plugin_id):
+        print(
+            f"Error: Plugin ID '{plugin_id}' does not match required format "
+            "com.<vendor>.<name> (lowercase, alphanumeric + underscore).",
+            file=sys.stderr,
+        )
+        return 1
+    if not name:
+        print("Error: Display name is required.", file=sys.stderr)
+        return 1
+
+    if target.name == ".":
+        target = Path.cwd() / plugin_id.split(".")[-1]
+
+    if target.exists() and any(target.iterdir()):
+        print(f"Error: Directory '{target}' already exists and is not empty.", file=sys.stderr)
+        return 1
+
+    target.mkdir(parents=True, exist_ok=True)
+    (target / "plugin.json").write_text(_generate_manifest(plugin_id, name, description) + "\n")
+    (target / "main.py").write_text(_generate_main(name))
+    (target / "settings.json").write_text(_generate_settings() + "\n")
+
+    print(f"\nCreated plugin scaffold in {target}/")
+    print("  plugin.json   — manifest")
+    print(f"  main.py       — {_to_class_name(name)} (BasePlugin subclass)")
+    print("  settings.json — settings schema (empty)")
+    print("\nNext steps:")
+    print("  1. Build your UI in on_ready()")
+    print(f"  2. Run: forkbit plugin validate {target}")
+    print(f"  3. Run: forkbit plugin build {target}")
+    return 0
+
+
+def register(subparsers) -> None:
+    p = subparsers.add_parser("init", help="Scaffold a new plugin project")
+    p.add_argument("dir", nargs="?", default=".", help="Directory to create plugin in")
+    p.add_argument("--id", help="Plugin ID (non-interactive mode)")
+    p.add_argument("--name", help="Display name (non-interactive mode)")
+    p.add_argument("--description", default="", help="Description (non-interactive mode)")
+    p.add_argument(
+        "--non-interactive", action="store_true",
+        help="Skip prompts, use --id/--name/--description flags",
+    )