update commit prev

plugins/README.md

@@ -1,14 +1,28 @@
-# External Plugins
+# Plugins
 
-Drop user plugins in this folder to make them available to the app without editing the built-in `Provider/` package.
+This folder is the primary home for bundled plugins and also the default search
+path for drop-in plugins.
 
-Supported discovery paths:
+Preferred layout:
+- Put each plugin in its own folder under `plugins/<name>/` with an `__init__.py`.
+- Keep plugin-specific assets beside the code in that same folder.
+- Single-file `.py` plugins are still supported, but package folders are the
+    recommended plug-and-play format.
+
+That means a plugin can ship as a drag-and-drop folder with extras such as:
+- `cookies.txt`
+- templates or fixture files
+- helper modules
+- small static assets
+
+Built-in bundled plugins use the same layout as external plugins. Additional
+drop-in plugin search paths are:
 - `plugins/` in the repo root
 - `plugins/` in the current working directory
 - Any directory listed in `MM_PLUGIN_PATH`
 - Any directory listed in `MEDEIA_PLUGIN_PATH`
 
-Plugin module rules:
+Plugin rules:
 - A plugin can be a single `.py` file or a package directory with `__init__.py`.
 - Define a class that inherits from `ProviderCore.base.Provider`.
 - Give it a stable name using `PLUGIN_NAME` or the class name.
@@ -34,6 +48,4 @@ class MyPlugin(Provider):
                 path=f"https://example.com/{text}",
             )
         ]
-```
-
-Built-in plugins still live in `Provider/`.
+```

plugins/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in plugin package.
+
+This package is the primary home for bundled plugins. Each built-in plugin
+should live in its own module or package under ``plugins/`` so it can also be
+distributed as a drag-and-drop drop-in with any sibling assets it needs.
+"""

plugins/example_provider.py

@@ -0,0 +1,7 @@
+"""Plugin-namespace import shim for the strict adapter example module.
+
+This keeps example docs pointing at the plugin namespace while the original
+implementation remains in ``Provider.example_provider`` for compatibility.
+"""
+
+from Provider.example_provider import *  # noqa: F401,F403

plugins/hifi/__init__.py

@@ -18,7 +18,7 @@ from API.Tidal import (
 )
 from ProviderCore.base import Provider, SearchResult, parse_inline_query_arguments
 from SYS.field_access import get_field
-from Provider.tidal_manifest import resolve_tidal_manifest_path
+from plugins.tidal_manifest import resolve_tidal_manifest_path
 from SYS import pipeline as pipeline_context
 from SYS.logger import debug, debug_panel, log
 

plugins/internetarchive/__init__.py

@@ -694,7 +694,7 @@ class InternetArchive(Provider):
 
     def _download_via_openlibrary(self, url: str, output_dir: Path) -> Optional[Dict[str, Any]]:
         try:
-            from Provider.openlibrary import OpenLibrary
+            from plugins.openlibrary import OpenLibrary
         except Exception as exc:
             log(f"[internetarchive] OpenLibrary borrow helper unavailable: {exc}", file=sys.stderr)
             return None
@@ -766,7 +766,7 @@ class InternetArchive(Provider):
             return None
 
         try:
-            from Provider.openlibrary import OpenLibrary
+            from plugins.openlibrary import OpenLibrary
         except Exception as exc:
             log(f"[internetarchive] OpenLibrary auth helper unavailable: {exc}", file=sys.stderr)
             return None

plugins/libgen/__init__.py

@@ -383,7 +383,7 @@ def _enrich_book_tags_from_isbn(isbn: str,
 
     # 2) isbnsearch metadata provider fallback.
     try:
-        from Provider.metadata_provider import get_metadata_provider
+        from plugins.metadata_provider import get_metadata_provider
 
         provider = get_metadata_provider("isbnsearch",
                                          config or {})

plugins/metadata_provider.py

@@ -0,0 +1,7 @@
+"""Plugin-namespace import shim for metadata helper utilities.
+
+The implementation currently lives in ``Provider.metadata_provider`` while the
+legacy namespace is phased out. New imports should prefer ``plugins``.
+"""
+
+from Provider.metadata_provider import *  # noqa: F401,F403

plugins/openlibrary/__init__.py

@@ -22,7 +22,7 @@ from ProviderCore.base import Provider, SearchResult
 from SYS.utils import sanitize_filename
 from SYS.cli_syntax import get_field, get_free_text, parse_query
 from SYS.logger import log
-from Provider.metadata_provider import (
+from plugins.metadata_provider import (
     archive_item_metadata_to_tags,
     fetch_archive_item_metadata,
 )

plugins/tidal/__init__.py

@@ -18,7 +18,7 @@ from API.Tidal import (
 )
 from ProviderCore.base import Provider, SearchResult
 from SYS.field_access import get_field
-from Provider.tidal_manifest import resolve_tidal_manifest_path
+from plugins.tidal_manifest import resolve_tidal_manifest_path
 from SYS import pipeline as pipeline_context
 from SYS.logger import debug, log
 

plugins/tidal_manifest.py

@@ -0,0 +1,7 @@
+"""Plugin-namespace import shim for Tidal/HIFI manifest helpers.
+
+The implementation currently lives in ``Provider.tidal_manifest`` while the
+legacy namespace is phased out. New imports should prefer ``plugins``.
+"""
+
+from Provider.tidal_manifest import *  # noqa: F401,F403