Add plugin transform type infrastructure

_plugin_harness.py: standalone script run inside each plugin's isolated
venv. Supports two modes: --discover <module> (returns transformer class
metadata as JSON) and <metadata_json> (runs a transform, returning a JSON
result object with output, success, stderr, and binary fields).

plugin.py: PluginTransformer class that creates and manages a per-plugin
venv under sandbox_dir/plugins/<module>/venv, runs discovery via the
harness, and dispatches transform calls as subprocesses.

transform-plugins.schema.yaml: schema for transform-plugins.yml, covering
pip deps, module paths, and optional url override.

Author: avillar

ogc/bblocks/schemas/transform-plugins.schema.yaml

@@ -0,0 +1,44 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: transform-plugins.yml
+description: Declares external transformer plugins to load at postprocessing startup.
+type: object
+properties:
+  plugins:
+    type: array
+    items:
+      type: object
+      required:
+        - modules
+      properties:
+        pip:
+          description: >
+            One or more pip install specifiers for packages that provide the plugin modules.
+            Accepts any specifier that `pip install` understands (package name, version
+            constraint, GitHub URL, etc.).
+          oneOf:
+            - type: string
+            - type: array
+              items:
+                type: string
+              minItems: 1
+        modules:
+          description: >
+            One or more dotted Python module paths to import. Each module is scanned for
+            classes that implement the Transformer duck type (a non-empty `transform_types`
+            list and a callable `transform` method).
+          oneOf:
+            - type: string
+            - type: array
+              items:
+                type: string
+              minItems: 1
+        url:
+          type: string
+          format: uri
+          description: >
+            URL for this plugin (e.g. its repository or PyPI page). If omitted, the
+            postprocessor attempts to derive one automatically from the `pip` specifier.
+            Provide this to override the derived URL or to supply one when auto-detection
+            is not possible (e.g. for local file installs).
+      additionalProperties: false
+additionalProperties: false

ogc/bblocks/transformers/_plugin_harness.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+Harness for plugin transform types. Two modes:
+
+  Discover:
+    python _plugin_harness.py --discover <module_path>
+
+    Scans the module for transformer classes and writes a JSON array to stdout:
+      [{"types": [...], "default_inputs": [...], "default_outputs": [...]}, ...]
+
+  Transform:
+    python _plugin_harness.py <metadata_json>
+
+    Reads input data from stdin, runs the transform, and writes a JSON object
+    to stdout:
+      {"success": true,  "output": "<str>",    "binary": false, "stderr": null}
+      {"success": true,  "output": "<base64>", "binary": true,  "stderr": null}
+      {"success": false, "output": null,        "binary": false, "stderr": "<str>"}
+
+    The metadata object passed to transform() has these attributes:
+      type             (str)   transform type identifier
+      transform_content (str)  code/script declared in transforms.yaml
+      input_data       (str)   example snippet text
+      source_mime_type (str)
+      target_mime_type (str)
+      metadata         (dict)  extra metadata (keys starting with _ excluded)
+      sandbox_dir      None    always None in subprocess context
+"""
+import importlib
+import inspect
+import json
+import sys
+from base64 import b64encode
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _transformer_classes(module):
+    """Yield (cls,) for every transformer class defined in module."""
+    module_name = module.__name__
+    for _, cls in inspect.getmembers(module, inspect.isclass):
+        if cls.__module__ != module_name:
+            continue
+        types = getattr(cls, 'transform_types', None)
+        if types and isinstance(types, list) and all(isinstance(t, str) for t in types):
+            yield cls
+
+
+class _Meta:
+    """Minimal TransformMetadata-compatible namespace passed to plugin transform()."""
+    __slots__ = ('type', 'transform_content', 'input_data',
+                 'source_mime_type', 'target_mime_type', 'metadata', 'sandbox_dir')
+
+
+# ---------------------------------------------------------------------------
+# Discover mode
+# ---------------------------------------------------------------------------
+
+def _discover(module_path: str) -> None:
+    module = importlib.import_module(module_path)
+    result = [
+        {
+            'class': cls.__name__,
+            'types': list(cls.transform_types),
+            'default_inputs': list(getattr(cls, 'default_inputs', None) or []),
+            'default_outputs': list(getattr(cls, 'default_outputs', None) or []),
+        }
+        for cls in _transformer_classes(module)
+    ]
+    print(json.dumps(result))
+
+
+# ---------------------------------------------------------------------------
+# Transform mode
+# ---------------------------------------------------------------------------
+
+def _transform(meta_json: str) -> None:
+    meta_dict = json.loads(meta_json)
+
+    m = _Meta()
+    m.type = meta_dict['type']
+    m.transform_content = meta_dict['transform_content']
+    m.source_mime_type = meta_dict['source_mime_type']
+    m.target_mime_type = meta_dict['target_mime_type']
+    m.metadata = meta_dict.get('metadata', {})
+    m.input_data = sys.stdin.buffer.read().decode('utf-8')
+    m.sandbox_dir = None
+
+    module_path = meta_dict['module']
+    transform_type = meta_dict['type']
+    module = importlib.import_module(module_path)
+
+    transformer = next(
+        (cls() for cls in _transformer_classes(module)
+         if transform_type in cls.transform_types),
+        None,
+    )
+
+    if transformer is None:
+        print(json.dumps({
+            'success': False, 'output': None, 'binary': False,
+            'stderr': f"No transformer found for type '{transform_type}' in '{module_path}'",
+        }))
+        return
+
+    try:
+        result = transformer.transform(m)
+    except Exception as e:
+        print(json.dumps({
+            'success': False, 'output': None, 'binary': False, 'stderr': str(e),
+        }))
+        return
+
+    if result is None:
+        print(json.dumps({'success': True, 'output': None, 'binary': False, 'stderr': None}))
+        return
+
+    if isinstance(result, bytes):
+        print(json.dumps({
+            'success': True,
+            'output': b64encode(result).decode('ascii'),
+            'binary': True,
+            'stderr': None,
+        }))
+    else:
+        print(json.dumps({'success': True, 'output': result, 'binary': False, 'stderr': None}))
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print('Usage: _plugin_harness.py --discover <module> | <metadata_json>',
+              file=sys.stderr)
+        sys.exit(1)
+
+    if sys.argv[1] == '--discover':
+        if len(sys.argv) < 3:
+            print('Usage: _plugin_harness.py --discover <module>', file=sys.stderr)
+            sys.exit(1)
+        _discover(sys.argv[2])
+    else:
+        _transform(sys.argv[1])

ogc/bblocks/transformers/plugin.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from base64 import b64decode
+from pathlib import Path
+
+from ogc.bblocks.models import TransformMetadata, TransformResult
+
+_HARNESS = Path(__file__).parent / '_plugin_harness.py'
+
+
+class PluginTransformer:
+
+    def __init__(self, module_path: str, pip_deps: list[str], transform_types: list[str]):
+        self.module_path = module_path
+        self.pip_deps = pip_deps
+        self.transform_types = transform_types
+        self.default_inputs: list = []
+        self.default_outputs: list = []
+
+    def ensure_venv(self, sandbox_dir: Path) -> Path:
+        slug = self.module_path.replace('.', '_')
+        venv_dir = sandbox_dir / 'plugins' / slug / 'venv'
+        if not venv_dir.exists():
+            print(f"  > Setting up plugin venv for '{self.module_path}'"
+                  + (f" (pip: {self.pip_deps})" if self.pip_deps else ""),
+                  file=sys.stderr)
+            subprocess.run([sys.executable, '-m', 'venv', str(venv_dir)], check=True)
+            if self.pip_deps:
+                pip_bin = venv_dir / 'bin' / 'pip'
+                subprocess.run(
+                    [str(pip_bin), 'install', '--quiet',
+                     '--disable-pip-version-check', *self.pip_deps],
+                    check=True,
+                )
+        return venv_dir
+
+    @staticmethod
+    def discover(venv_dir: Path, module_path: str) -> list[dict]:
+        """Run --discover and return the list of transformer class descriptors."""
+        python_bin = venv_dir / 'bin' / 'python'
+        result = subprocess.run(
+            [str(python_bin), str(_HARNESS), '--discover', module_path],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            return []
+        try:
+            return json.loads(result.stdout.strip())
+        except Exception:
+            return []
+
+    def transform(self, metadata: TransformMetadata) -> TransformResult:
+        if not metadata.sandbox_dir:
+            return TransformResult(
+                output=None, success=False,
+                stderr='Plugin transforms require a sandbox directory',
+            )
+
+        venv_dir = self.ensure_venv(metadata.sandbox_dir)
+        python_bin = venv_dir / 'bin' / 'python'
+
+        meta_dict = {
+            'type': metadata.type,
+            'module': self.module_path,
+            'transform_content': metadata.transform_content,
+            'source_mime_type': metadata.source_mime_type,
+            'target_mime_type': metadata.target_mime_type,
+            'metadata': {k: v for k, v in (metadata.metadata or {}).items()
+                         if not k.startswith('_')},
+        }
+
+        result = subprocess.run(
+            [str(python_bin), str(_HARNESS), json.dumps(meta_dict)],
+            input=(metadata.input_data.encode('utf-8')
+                   if isinstance(metadata.input_data, str)
+                   else metadata.input_data),
+            capture_output=True,
+        )
+
+        try:
+            data = json.loads(result.stdout)
+        except Exception:
+            stderr = result.stderr.decode('utf-8', errors='replace') or 'Unexpected harness error'
+            return TransformResult(output=None, success=False, stderr=stderr)
+
+        output = data.get('output')
+        if output is not None and data.get('binary'):
+            output = b64decode(output)
+
+        return TransformResult(
+            output=output,
+            success=data.get('success', False),
+            stderr=data.get('stderr') or None,
+            binary=bool(data.get('binary')),
+        )