Add support for the 'decky_plugin' module exposed by decky-loader (#16)

* Add support for the 'decky_plugin' module exposed by decky-loader

* Make versioned 'decky_plugin.pyi' stub interface and 'py_modules'
support available

* Add rule to ignore 'decky_plugin.py'

.gitignore

@@ -44,3 +44,6 @@ yalc.lock
 # Ignore output folder
 
 backend/out
+
+# Make sure to ignore any instance of the loader's decky_plugin.py
+decky_plugin.py

decky_plugin.pyi

@@ -0,0 +1,173 @@
+"""
+This module exposes various constants and helpers useful for decky plugins.
+
+* Plugin's settings and configurations should be stored under `DECKY_PLUGIN_SETTINGS_DIR`.
+* Plugin's runtime data should be stored under `DECKY_PLUGIN_RUNTIME_DIR`.
+* Plugin's persistent log files should be stored under `DECKY_PLUGIN_LOG_DIR`.
+
+Avoid writing outside of `DECKY_HOME`, storing under the suggested paths is strongly recommended.
+
+Some basic migration helpers are available: `migrate_any`, `migrate_settings`, `migrate_runtime`, `migrate_logs`.
+
+A logging facility `logger` is available which writes to the recommended location.
+"""
+
+__version__ = '0.1.0'
+
+import logging
+
+"""
+Constants
+"""
+
+HOME: str
+"""
+The home directory of the effective user running the process.
+Environment variable: `HOME`.
+If `root` was specified in the plugin's flags it will be `/root` otherwise the user whose home decky resides in.
+e.g.: `/home/deck`
+"""
+
+USER: str
+"""
+The effective username running the process.
+Environment variable: `USER`.
+It would be `root` if `root` was specified in the plugin's flags otherwise the user whose home decky resides in.
+e.g.: `deck`
+"""
+
+DECKY_VERSION: str
+"""
+The version of the decky loader.
+Environment variable: `DECKY_VERSION`.
+e.g.: `v2.5.0-pre1`
+"""
+
+DECKY_USER: str
+"""
+The user whose home decky resides in.
+Environment variable: `DECKY_USER`.
+e.g.: `deck`
+"""
+
+DECKY_USER_HOME: str
+"""
+The home of the user where decky resides in.
+Environment variable: `DECKY_USER_HOME`.
+e.g.: `/home/deck`
+"""
+
+DECKY_HOME: str
+"""
+The root of the decky folder.
+Environment variable: `DECKY_HOME`.
+e.g.: `/home/deck/homebrew`
+"""
+
+DECKY_PLUGIN_SETTINGS_DIR: str
+"""
+The recommended path in which to store configuration files (created automatically).
+Environment variable: `DECKY_PLUGIN_SETTINGS_DIR`.
+e.g.: `/home/deck/homebrew/settings/decky-plugin-template`
+"""
+
+DECKY_PLUGIN_RUNTIME_DIR: str
+"""
+The recommended path in which to store runtime data (created automatically).
+Environment variable: `DECKY_PLUGIN_RUNTIME_DIR`.
+e.g.: `/home/deck/homebrew/data/decky-plugin-template`
+"""
+
+DECKY_PLUGIN_LOG_DIR: str
+"""
+The recommended path in which to store persistent logs (created automatically).
+Environment variable: `DECKY_PLUGIN_LOG_DIR`.
+e.g.: `/home/deck/homebrew/logs/decky-plugin-template`
+"""
+
+DECKY_PLUGIN_DIR: str
+"""
+The root of the plugin's directory.
+Environment variable: `DECKY_PLUGIN_DIR`.
+e.g.: `/home/deck/homebrew/plugins/decky-plugin-template`
+"""
+
+DECKY_PLUGIN_NAME: str
+"""
+The name of the plugin as specified in the 'plugin.json'.
+Environment variable: `DECKY_PLUGIN_NAME`.
+e.g.: `Example Plugin`
+"""
+
+DECKY_PLUGIN_VERSION: str
+"""
+The version of the plugin as specified in the 'package.json'.
+Environment variable: `DECKY_PLUGIN_VERSION`.
+e.g.: `0.0.1`
+"""
+
+DECKY_PLUGIN_AUTHOR: str
+"""
+The author of the plugin as specified in the 'plugin.json'.
+Environment variable: `DECKY_PLUGIN_AUTHOR`.
+e.g.: `John Doe`
+"""
+
+DECKY_PLUGIN_LOG: str
+"""
+The path to the plugin's main logfile.
+Environment variable: `DECKY_PLUGIN_LOG`.
+e.g.: `/home/deck/homebrew/logs/decky-plugin-template/plugin.log`
+"""
+
+"""
+Migration helpers
+"""
+
+
+def migrate_any(target_dir: str, *files_or_directories: str) -> dict[str, str]:
+    """
+    Migrate files and directories to a new location and remove old locations.
+    Specified files will be migrated to `target_dir`.
+    Specified directories will have their contents recursively migrated to `target_dir`.
+
+    Returns the mapping of old -> new location.
+    """
+
+
+def migrate_settings(*files_or_directories: str) -> dict[str, str]:
+    """
+    Migrate files and directories relating to plugin settings to the recommended location and remove old locations.
+    Specified files will be migrated to `DECKY_PLUGIN_SETTINGS_DIR`.
+    Specified directories will have their contents recursively migrated to `DECKY_PLUGIN_SETTINGS_DIR`.
+
+    Returns the mapping of old -> new location.
+    """
+
+
+def migrate_runtime(*files_or_directories: str) -> dict[str, str]:
+    """
+    Migrate files and directories relating to plugin runtime data to the recommended location and remove old locations
+    Specified files will be migrated to `DECKY_PLUGIN_RUNTIME_DIR`.
+    Specified directories will have their contents recursively migrated to `DECKY_PLUGIN_RUNTIME_DIR`.
+
+    Returns the mapping of old -> new location.
+    """
+
+
+def migrate_logs(*files_or_directories: str) -> dict[str, str]:
+    """
+    Migrate files and directories relating to plugin logs to the recommended location and remove old locations.
+    Specified files will be migrated to `DECKY_PLUGIN_LOG_DIR`.
+    Specified directories will have their contents recursively migrated to `DECKY_PLUGIN_LOG_DIR`.
+
+    Returns the mapping of old -> new location.
+    """
+
+
+"""
+Logging
+"""
+
+logger: logging.Logger
+"""The main plugin logger writing to `DECKY_PLUGIN_LOG`."""

main.py

@@ -1,11 +1,10 @@
-import logging
+import os
+
+# The decky plugin module is located at decky-loader/plugin
+# For easy intellisense checkout the decky-loader code one directory up
+# or add the `decky-loader/plugin` path to `python.analysis.extraPaths` in `.vscode/settings.json`
+import decky_plugin
 
-logging.basicConfig(filename="/tmp/template.log",
-                    format='[Template] %(asctime)s %(levelname)s %(message)s',
-                    filemode='w+',
-                    force=True)
-logger=logging.getLogger()
-logger.setLevel(logging.INFO) # can be changed to logging.DEBUG for debugging issues
 
 class Plugin:
     # A normal method. It can be called from JavaScript using call_plugin_function("method_1", argument1, argument2)
@@ -14,9 +13,29 @@ class Plugin:
 
     # Asyncio-compatible long-running code, executed in a task when the plugin is loaded
     async def _main(self):
-        logger.info("Hello World!")
+        decky_plugin.logger.info("Hello World!")
 
     # Function called first during the unload process, utilize this to handle your plugin being removed
     async def _unload(self):
-        logger.info("Goodbye World!")
+        decky_plugin.logger.info("Goodbye World!")
         pass
+
+    # Migrations that should be performed before entering `_main()`.
+    async def _migration(self):
+        decky_plugin.logger.info("Migrating")
+        # Here's a migration example for logs:
+        # - `~/.config/decky-template/template.log` will be migrated to `decky_plugin.DECKY_PLUGIN_LOG_DIR/template.log`
+        decky_plugin.migrate_logs(os.path.join(decky_plugin.DECKY_USER_HOME,
+                                               ".config", "decky-template", "template.log"))
+        # Here's a migration example for settings:
+        # - `~/homebrew/settings/template.json` is migrated to `decky_plugin.DECKY_PLUGIN_SETTINGS_DIR/template.json`
+        # - `~/.config/decky-template/` all files and directories under this root are migrated to `decky_plugin.DECKY_PLUGIN_SETTINGS_DIR/`
+        decky_plugin.migrate_settings(
+            os.path.join(decky_plugin.DECKY_HOME, "settings", "template.json"),
+            os.path.join(decky_plugin.DECKY_USER_HOME, ".config", "decky-template"))
+        # Here's a migration example for runtime data:
+        # - `~/homebrew/template/` all files and directories under this root are migrated to `decky_plugin.DECKY_PLUGIN_RUNTIME_DIR/`
+        # - `~/.local/share/decky-template/` all files and directories under this root are migrated to `decky_plugin.DECKY_PLUGIN_RUNTIME_DIR/`
+        decky_plugin.migrate_runtime(
+            os.path.join(decky_plugin.DECKY_HOME, "template"),
+            os.path.join(decky_plugin.DECKY_USER_HOME, ".local", "share", "decky-template"))