forkbit-sdk 0.1.0

Plugin SDK for building ForkBit plugins

ForkBit SDK

Build plugins for ForkBit — the desktop app for managing app store workflows.

Installation

pip install forkbit-sdk

Quick Start

Create a new plugin:

forkbit plugin init my_plugin

This generates a ready-to-run plugin scaffold:

my_plugin/
  plugin.json    — manifest (id, name, version, dependencies)
  main.py        — your plugin code (BasePlugin subclass)
  settings.json  — settings schema

Writing a Plugin

Every plugin is a BasePlugin subclass that builds its UI in on_ready():

from PySide6.QtCore import Qt
from PySide6.QtWidgets import QLabel, QVBoxLayout

from forkbit_sdk import BasePlugin


class MyPlugin(BasePlugin):

    def on_ready(self) -> None:
        layout = QVBoxLayout(self.container)
        layout.setAlignment(Qt.AlignmentFlag.AlignTop)

        label = QLabel("Hello from my plugin!")
        layout.addWidget(label)

Your plugin inherits the app's theme automatically — standard PySide6 widgets just work.

Plugin API

Property / Method	Description
self.container	QWidget — build your UI inside this
self.settings	dict — current plugin settings values
self.project_id	str — current project ID
self.project_path	str — path to the project directory
self.data_dir	Path — per-instance storage directory
self.git	GitClient — git operations (status, tags, push, pull, commit)
self.read_json(filename)	Read JSON from data_dir
self.write_json(filename, data)	Atomic-write JSON to data_dir
self.notify(message, level)	Show a toast notification
self.translate(text, src, tgt, on_done, on_error)	Async translation
self.set_subtitle(text)	Update the plugin header subtitle
self.secret_file(field_id)	Get raw bytes of a secret file setting
on_ready()	Override to build UI and initialize state
on_settings_changed(settings)	Override to react to settings changes

Settings Schema

Define user-configurable settings in settings.json:

{
  "fields": [
    { "id": "api_key", "label": "API Key", "type": "password" },
    { "id": "auto_sync", "label": "Auto-sync on save", "type": "bool", "default": true }
  ]
}

Supported types: text, password, textarea, bool, secret_file.

Plugin Manifest

plugin.json defines your plugin's metadata:

{
  "id": "com.mycompany.myplugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "What it does",
  "entry": "main.py",
  "min_app_version": "0.2.0",
  "requirements": []
}

CLI Commands

forkbit plugin init [dir]        # scaffold a new plugin
forkbit plugin validate [dir]    # check manifest and imports
forkbit plugin build [dir]       # build for current platform
forkbit plugin release [dir]     # build for all platforms

License

MIT