3lc-compute-plugin-sdk 0.2.2__py3-none-any.whl

tlc_plugin_sdk/shared/config_store.py

@@ -0,0 +1,140 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+"""Generic on-disk store for a plugin's saved job configs.
+
+A "config" here is a **reusable job parameterization** a user names and re-runs
+from the plugin UI (the "New config" / config-bar feature driven by
+:func:`tlc_plugin_sdk.shared.config_ui.config_ui_script`) — NOT the
+service/host settings (those live in ``persistent_settings`` / ``settings.json``).
+
+Each plugin keeps its own ``@dataclass`` config schema and hands the *type* to
+:class:`PluginConfigStore`, which owns the JSON-on-disk CRUD. The config
+dataclass must carry the common envelope fields the store manages:
+
+- ``id: str``         — assigned on first save
+- ``created: str``    — ISO timestamp, assigned on first save; list order key
+- ``last_run: str | None`` — bumped by :meth:`update_last_run`
+
+(``name: str`` is conventional for the UI but not required by the store.)
+
+Configs live under ``~/.3lc-plugin-configs/<plugin-id>/``. Pass ``legacy_dir``
+to lazily migrate a pre-standardization location on first construction.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+import uuid
+from dataclasses import asdict, is_dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Generic, TypeVar
+
+logger = logging.getLogger(__name__)
+
+# Standardized root for all plugins' saved job configs.
+CONFIG_ROOT = Path.home() / ".3lc-plugin-configs"
+
+T = TypeVar("T")
+
+
+class PluginConfigStore(Generic[T]):
+    """Persist a plugin's saved job configs as JSON files, one per config.
+
+    Args:
+        config_cls: The plugin's config ``@dataclass`` (must have ``id`` /
+            ``created`` / ``last_run`` fields). Instances are (de)serialized via
+            :func:`dataclasses.asdict` and ``config_cls(**known_fields)``.
+        plugin_id: The plugin's manifest id; configs live under
+            ``~/.3lc-plugin-configs/<plugin_id>/``.
+        legacy_dir: Optional back-compat directory. If the standardized
+            directory has no configs yet and ``legacy_dir`` holds some, they are
+            moved on construction (one-time, idempotent).
+
+    """
+
+    def __init__(self, config_cls: type[T], plugin_id: str, *, legacy_dir: Path | str | None = None) -> None:
+        if not is_dataclass(config_cls):
+            msg = f"PluginConfigStore requires a dataclass config type, got {config_cls!r}"
+            raise TypeError(msg)
+        self._cls = config_cls
+        self._dir = CONFIG_ROOT / plugin_id
+        self._dir.mkdir(parents=True, exist_ok=True)
+        if legacy_dir is not None:
+            self._migrate_legacy(Path(legacy_dir))
+
+    # ── CRUD ─────────────────────────────────────────────────────────────
+    def list_configs(self) -> list[T]:
+        """Return all saved configs, newest first (by ``created``)."""
+        configs: list[T] = []
+        for f in sorted(self._dir.glob("*.json")):
+            cfg = self._read(f)
+            if cfg is not None:
+                configs.append(cfg)
+        configs.sort(key=lambda c: getattr(c, "created", "") or "", reverse=True)
+        return configs
+
+    def get_config(self, config_id: str) -> T | None:
+        """Load a config by id, or None if missing/unreadable."""
+        return self._read(self._path(config_id))
+
+    def save_config(self, config: T) -> T:
+        """Save a config, assigning ``id`` and ``created`` on first save."""
+        if not getattr(config, "id", ""):
+            config.id = str(uuid.uuid4())  # type: ignore[attr-defined]
+        if not getattr(config, "created", ""):
+            config.created = datetime.now(timezone.utc).isoformat()  # type: ignore[attr-defined]
+        with open(self._path(config.id), "w") as f:  # type: ignore[attr-defined]
+            json.dump(asdict(config), f, indent=2)  # type: ignore[call-overload]
+        return config
+
+    def delete_config(self, config_id: str) -> bool:
+        """Delete a config. Returns True if it existed."""
+        path = self._path(config_id)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    def update_last_run(self, config_id: str) -> None:
+        """Stamp ``last_run`` with the current time, if the config exists."""
+        config = self.get_config(config_id)
+        if config is not None:
+            config.last_run = datetime.now(timezone.utc).isoformat()  # type: ignore[attr-defined]
+            self.save_config(config)
+
+    # ── internals ────────────────────────────────────────────────────────
+    def _path(self, config_id: str) -> Path:
+        return self._dir / f"{config_id}.json"
+
+    def _read(self, path: Path) -> T | None:
+        """Load + deserialize one config file, tolerating drift/corruption.
+
+        Unknown keys (older/newer schema) are dropped and missing fields fall
+        back to dataclass defaults, so a config schema can evolve without
+        invalidating saved files.
+        """
+        if not path.exists():
+            return None
+        try:
+            with open(path) as f:
+                data = json.load(f)
+            known = {k: v for k, v in data.items() if k in self._cls.__dataclass_fields__}  # type: ignore[attr-defined]
+            return self._cls(**known)
+        except (json.JSONDecodeError, OSError, TypeError):
+            return None
+
+    def _migrate_legacy(self, legacy_dir: Path) -> None:
+        """Move configs from a pre-standardization dir into the new location once."""
+        if not legacy_dir.is_dir() or any(self._dir.glob("*.json")):
+            return
+        moved = 0
+        for f in legacy_dir.glob("*.json"):
+            dest = self._dir / f.name
+            if not dest.exists():
+                shutil.move(str(f), str(dest))
+                moved += 1
+        if moved:
+            logger.info("Migrated %d config(s) from %s → %s", moved, legacy_dir, self._dir)

tlc_plugin_sdk/shared/config_ui.py

@@ -0,0 +1,256 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+"""Shared config bar UI for plugins — JS module injected into plugin fragments.
+
+Follows the same injection pattern as ``alias_ui.py``.  Plugins call
+``config_ui_script()`` to get the JS string, then inject it with
+``inject_scripts(raw, config_ui_script())`` (see ``ui_inject.py``).
+
+The module exposes a single factory:
+
+    var cfg = _tlcPluginConfig({ prefix, apiPath, storageKey,
+                                 collectFn, populateFn, labelFn,
+                                 onNew, onLoad });
+    cfg.init();
+
+See doc-block inside CONFIG_UI_JS for full API.
+"""
+
+from __future__ import annotations
+
+CONFIG_UI_JS = r"""
+/* ── Shared Plugin Config Manager ────────────────────────────────
+ *
+ * Factory that returns a config-bar controller.  Handles:
+ *   - list / load / save / saveAsNew / delete via REST
+ *   - localStorage for last-selected config ID
+ *   - dirty-tracking (snapshot-based) with "Save New" visibility
+ *   - dropdown population with custom label
+ *
+ * Required HTML IDs (by convention, {prefix}-config-select, etc.):
+ *   {prefix}-config-select   — <select> dropdown
+ *   {prefix}-save-new-btn    — "Save New" button (hidden by default)
+ *   {prefix}-delete-btn      — "Delete" button (hidden by default)
+ *
+ * Options:
+ *   prefix      {string}    HTML ID prefix (e.g. "im", "dc")
+ *   apiPath     {string}    REST endpoint base (e.g. "/api/plugins/image-metrics/configs")
+ *   storageKey  {string}    localStorage key for last config ID
+ *   collectFn   {function}  () => formDataObject (must include .name)
+ *   populateFn  {function}  (config) => void — fill form from config
+ *   labelFn     {function}  (config) => string — dropdown label
+ *   onNew       {function}  () => void — extra reset logic
+ *   onLoad      {function}  (config) => void — extra post-load logic
+ * ──────────────────────────────────────────────────────────────── */
+function _tlcPluginConfig(opts) {
+  var prefix     = opts.prefix;
+  var apiPath    = opts.apiPath;
+  var storageKey = opts.storageKey;
+  var collectFn  = opts.collectFn;
+  var populateFn = opts.populateFn;
+  var labelFn    = opts.labelFn  || function(c) { return c.name || "Untitled"; };
+  var onNew      = opts.onNew    || function() {};
+  var onLoad     = opts.onLoad   || function() {};
+
+  var _currentId = null;
+  var _snapshot  = null;
+  var _timer     = null;
+
+  var _selId     = prefix + "-config-select";
+  var _saveNewId = prefix + "-save-new-btn";
+  var _deleteId  = prefix + "-delete-btn";
+
+  /* ── Auth-aware fetch ── */
+  function _fetch(url, reqOpts) {
+    if (window.PLUGIN_API && window.PLUGIN_API.authFetch) {
+      return window.PLUGIN_API.authFetch(url, reqOpts || {});
+    }
+    return fetch(url, reqOpts || {});
+  }
+
+  function _baseUrl() {
+    var base = "";
+    if (window.PLUGIN_API && window.PLUGIN_API.getConfig) {
+      base = window.PLUGIN_API.getConfig("compute_service_url") || "";
+    }
+    return base + apiPath;
+  }
+
+  /* ── Snapshot / dirty ── */
+  function takeSnapshot() {
+    try { _snapshot = JSON.stringify(collectFn()); } catch(e) { _snapshot = null; }
+  }
+
+  function checkDirty() {
+    var btn = document.getElementById(_saveNewId);
+    if (!btn) return;
+    try {
+      var data = collectFn();
+      var hasName = data.name && data.name.trim();
+      if (!_currentId) {
+        // New config: show "Save New" as soon as a name is entered
+        btn.style.display = hasName ? "" : "none";
+      } else {
+        // Existing config: show "Save New" when form has changed
+        var dirty = JSON.stringify(data) !== _snapshot;
+        btn.style.display = dirty ? "" : "none";
+      }
+    } catch(e) {}
+  }
+
+  function scheduleAutoSave() {
+    clearTimeout(_timer);
+    _timer = setTimeout(checkDirty, 300);
+  }
+
+  /* ── CRUD ── */
+  function loadAll() {
+    _fetch(_baseUrl())
+      .then(function(r) { return r.json(); })
+      .then(function(configs) {
+        var sel = document.getElementById(_selId);
+        if (!sel) return;
+        var prev = sel.value || (_currentId || "");
+        sel.innerHTML = '<option value="">New config</option>';
+        (Array.isArray(configs) ? configs : []).forEach(function(c) {
+          var opt = document.createElement("option");
+          opt.value = c.id;
+          opt.textContent = labelFn(c);
+          sel.appendChild(opt);
+        });
+        if (prev) sel.value = prev;
+      })
+      .catch(function() {});
+  }
+
+  function loadConfig(configId) {
+    _fetch(_baseUrl() + "/" + configId)
+      .then(function(r) { return r.json(); })
+      .then(function(c) {
+        if (c.error) return;
+        _currentId = c.id;
+        try { localStorage.setItem(storageKey, c.id); } catch(e) {}
+        populateFn(c);
+        var sel = document.getElementById(_selId);
+        if (sel) sel.value = c.id;
+        var saveBtn = document.getElementById(_saveNewId);
+        if (saveBtn) saveBtn.style.display = "";
+        var delBtn = document.getElementById(_deleteId);
+        if (delBtn) delBtn.style.display = "";
+        onLoad(c);
+        setTimeout(function() { takeSnapshot(); checkDirty(); }, 100);
+        loadAll();
+      })
+      .catch(function(e) { console.warn("Config load failed:", e); });
+  }
+
+  function onSelect(val) {
+    if (val) { loadConfig(val); } else { newConfig(); }
+  }
+
+  function newConfig() {
+    _currentId = null;
+    try { localStorage.removeItem(storageKey); } catch(e) {}
+    var sel = document.getElementById(_selId);
+    if (sel) sel.value = "";
+    var saveBtn = document.getElementById(_saveNewId);
+    if (saveBtn) saveBtn.style.display = "none";
+    var delBtn = document.getElementById(_deleteId);
+    if (delBtn) delBtn.style.display = "none";
+    onNew();
+    takeSnapshot();
+    loadAll();
+  }
+
+  function saveAsNew() {
+    var data = collectFn();
+    data.id = "";
+    if (!data.name || !data.name.trim()) {
+      alert("Please enter a config name.");
+      return;
+    }
+    _fetch(_baseUrl(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(data),
+    })
+    .then(function(r) { return r.json(); })
+    .then(function(resp) {
+      if (resp.error) { alert("Error: " + resp.error); return; }
+      _currentId = resp.id;
+      try { localStorage.setItem(storageKey, _currentId); } catch(e) {}
+      var delBtn = document.getElementById(_deleteId);
+      if (delBtn) delBtn.style.display = "";
+      takeSnapshot();
+      checkDirty();
+      loadAll();
+    })
+    .catch(function(e) { alert("Save failed: " + e); });
+  }
+
+  function save(silent) {
+    var data = collectFn();
+    data.id = _currentId || "";
+    if (!data.name || !data.name.trim()) {
+      if (!silent) alert("Please enter a config name.");
+      return;
+    }
+    _fetch(_baseUrl(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(data),
+    })
+    .then(function(r) { return r.json(); })
+    .then(function(resp) {
+      if (resp.error) { if (!silent) alert("Error: " + resp.error); return; }
+      _currentId = resp.id;
+      try { localStorage.setItem(storageKey, _currentId); } catch(e) {}
+      var delBtn = document.getElementById(_deleteId);
+      if (delBtn) delBtn.style.display = "";
+      takeSnapshot();
+      checkDirty();
+      loadAll();
+    })
+    .catch(function(e) { if (!silent) alert("Save failed: " + e); });
+  }
+
+  function deleteConfig() {
+    if (!_currentId) return;
+    if (!confirm("Delete this config?")) return;
+    _fetch(_baseUrl() + "/" + _currentId + "/delete", { method: "POST" })
+      .then(function() { newConfig(); })
+      .catch(function() {});
+  }
+
+  function init() {
+    var savedId = null;
+    try { savedId = localStorage.getItem(storageKey); } catch(e) {}
+    if (savedId) {
+      loadConfig(savedId);
+    } else {
+      loadAll();
+    }
+  }
+
+  return {
+    init: init,
+    loadAll: loadAll,
+    loadConfig: loadConfig,
+    onSelect: onSelect,
+    newConfig: newConfig,
+    save: save,
+    saveAsNew: saveAsNew,
+    deleteConfig: deleteConfig,
+    scheduleAutoSave: scheduleAutoSave,
+    takeSnapshot: takeSnapshot,
+    checkDirty: checkDirty,
+    getCurrentId: function() { return _currentId; },
+    setCurrentId: function(id) { _currentId = id; },
+  };
+}
+"""
+
+
+def config_ui_script() -> str:
+    """Return the shared config bar JavaScript for injection into plugin UI fragments."""
+    return CONFIG_UI_JS

tlc_plugin_sdk/shared/data_source_routes.py

@@ -0,0 +1,221 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+"""Reusable Litestar route handlers for data-source input widgets.
+
+Plugins that use the shared ``data_source`` UI component (see
+:mod:`~tlc_plugin_sdk.shared.data_source_ui`) should include these handlers in
+their ``get_route_handlers()`` list so the frontend widget can browse the compute
+node's filesystem and receive file uploads.
+
+Usage in a plugin's ``routes.py``::
+
+    from tlc_plugin_sdk.shared.data_source_routes import data_source_route_handlers
+
+
+    def get_route_handlers():
+        handlers = [my_handler_1, my_handler_2, ...]
+        handlers.extend(data_source_route_handlers())
+        return handlers
+
+The routes are:
+
+``GET /browse?path=<dir>&glob=<pattern>&show_hidden=false``
+    List files and directories visible on the compute node, **confined to the
+    allowed roots**. An empty or ``~`` path opens the first root.
+
+``POST /upload-temp``  (multipart ``data`` field)
+    Upload a file from the browser to a fresh private temp directory on the
+    compute node and return the server-side path.
+
+Confinement — these routes expose the compute node's filesystem to every
+authenticated hub user, so what they can reach is an operator decision, not the
+caller's:
+
+- ``/browse`` only lists paths inside the roots named by ``TLC_DATA_SOURCE_ROOTS``
+  (``os.pathsep``-separated directories; default: the service user's home). Every
+  requested path is ``realpath``-resolved before the containment check, so ``..``
+  segments and symlinks pointing outside a root are denied rather than followed.
+- ``/upload-temp`` ignores directory components of the client-supplied filename
+  (a ``../``-laden name cannot escape the upload dir) and rejects bodies larger
+  than ``TLC_DATA_SOURCE_MAX_UPLOAD_MB`` (default ``512``).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING, Annotated, Any
+
+from litestar import get, post
+from litestar.datastructures import UploadFile
+from litestar.enums import RequestEncodingType
+from litestar.params import Body
+
+if TYPE_CHECKING:
+    from litestar import Request
+    from litestar.handlers import BaseRouteHandler
+
+logger = logging.getLogger(__name__)
+
+#: Directories ``/browse`` may list, ``os.pathsep``-separated. Default: the user's home.
+ROOTS_ENV = "TLC_DATA_SOURCE_ROOTS"
+
+#: Upload size ceiling in MB for ``/upload-temp``. Default: :data:`DEFAULT_MAX_UPLOAD_MB`.
+MAX_UPLOAD_MB_ENV = "TLC_DATA_SOURCE_MAX_UPLOAD_MB"
+
+DEFAULT_MAX_UPLOAD_MB = 512
+
+
+def allowed_browse_roots() -> list[str]:
+    """Return the directories ``/browse`` may list, resolved and existing.
+
+    Read from :data:`ROOTS_ENV` (``os.pathsep``-separated). Entries are
+    tilde-expanded and ``realpath``-resolved; ones that are not existing
+    directories are dropped. Falls back to the user's home directory when the
+    variable is unset or nothing survives — a picker with zero roots is just a
+    broken picker, and home is the least surprising default.
+
+    Returns:
+        Resolved root directories, first one being the default browse target.
+
+    """
+    raw = os.environ.get(ROOTS_ENV, "")
+    candidates = [c for c in (part.strip() for part in raw.split(os.pathsep)) if c] or ["~"]
+    roots: list[str] = []
+    for candidate in candidates:
+        resolved = os.path.realpath(os.path.expanduser(candidate))
+        if os.path.isdir(resolved) and resolved not in roots:
+            roots.append(resolved)
+    return roots or [os.path.realpath(os.path.expanduser("~"))]
+
+
+def _confine_to_roots(path: str, roots: list[str]) -> str | None:
+    """Resolve ``path`` and return it when it lies inside one of ``roots``, else ``None``.
+
+    ``realpath`` first, contain second: a ``..`` segment or a symlink that points
+    outside a root resolves to its real target and is then denied, rather than the
+    literal path passing a prefix test it does not deserve.
+    """
+    resolved = os.path.realpath(os.path.expanduser(path))
+    for root in roots:
+        if resolved == root or resolved.startswith(root + os.sep):
+            return resolved
+    return None
+
+
+def _max_upload_mb() -> int:
+    """The upload ceiling in MB — :data:`MAX_UPLOAD_MB_ENV`, else the default."""
+    try:
+        value = int(os.environ.get(MAX_UPLOAD_MB_ENV, ""))
+    except ValueError:
+        value = 0
+    return value if value > 0 else DEFAULT_MAX_UPLOAD_MB
+
+
+def _safe_upload_name(raw: str | None) -> str:
+    """Reduce a client-supplied filename to a bare, safe basename.
+
+    Directory components are the client reaching for a *location*, which is not
+    theirs to choose — strip them (both separator flavors, whichever OS serves)
+    and refuse the dot names that survive ``basename``.
+    """
+    name = os.path.basename((raw or "").replace("\\", "/").strip())
+    if name in ("", ".", ".."):
+        return "upload"
+    return name
+
+
+def data_source_route_handlers() -> list[BaseRouteHandler]:
+    """Return browse + upload-temp route handlers for the data-source widget."""
+
+    @get("/browse", sync_to_thread=True)
+    def browse_filesystem(request: Request[Any, Any, Any]) -> dict[str, Any]:
+        """List files and directories at a compute-node path inside the allowed roots.
+
+        Query params:
+            path: Directory to list. Empty or ``~`` opens the first allowed root.
+            glob: Optional glob pattern to filter files (e.g. ``*.yaml``).
+            show_hidden: Whether to include dotfiles (default ``false``).
+        """
+        import fnmatch
+
+        roots = allowed_browse_roots()
+        raw_path = request.query_params.get("path", "").strip()
+        glob_pattern = request.query_params.get("glob", "")
+        show_hidden = request.query_params.get("show_hidden", "false").lower() == "true"
+
+        if not raw_path or raw_path == "~":
+            expanded = roots[0]
+        else:
+            candidate = os.path.expanduser(raw_path)
+            if not os.path.isabs(candidate):
+                return {"error": f"Path must be absolute (got {candidate!r})."}
+            confined = _confine_to_roots(candidate, roots)
+            if confined is None:
+                return {"error": f"Path is outside the allowed data-source roots: {candidate}"}
+            expanded = confined
+
+        if not os.path.exists(expanded):
+            return {"error": f"Path does not exist: {expanded}"}
+        if not os.path.isdir(expanded):
+            return {"error": f"Not a directory: {expanded}"}
+
+        active_root = next(r for r in roots if expanded == r or expanded.startswith(r + os.sep))
+
+        entries: list[dict[str, Any]] = []
+        try:
+            for entry in sorted(os.scandir(expanded), key=lambda e: (not e.is_dir(), e.name.lower())):
+                if not show_hidden and entry.name.startswith("."):
+                    continue
+                if glob_pattern and not entry.is_dir() and not fnmatch.fnmatch(entry.name, glob_pattern):
+                    continue
+                try:
+                    stat = entry.stat()
+                    entries.append({
+                        "name": entry.name,
+                        "type": "dir" if entry.is_dir() else "file",
+                        "size": stat.st_size if entry.is_file() else None,
+                    })
+                except OSError:
+                    continue
+        except PermissionError:
+            return {"error": f"Permission denied: {expanded}"}
+
+        return {
+            "path": expanded,
+            # Clamped at the containing root: "up" from a root is not a place this
+            # widget can go, so the UI gets no parent to offer.
+            "parent": os.path.dirname(expanded) if expanded != active_root else None,
+            "root": active_root,
+            "roots": roots,
+            "entries": entries,
+        }
+
+    @post("/upload-temp", status_code=200)
+    async def upload_temp(
+        data: Annotated[UploadFile, Body(media_type=RequestEncodingType.MULTI_PART)],
+    ) -> dict[str, Any]:
+        """Upload a file to a fresh temp directory and return the server-side path.
+
+        Used by data-source widgets that need to transfer a file from the
+        browser to the compute node's filesystem. Each upload lands in its own
+        ``mkdtemp`` directory (mode 0700), so concurrent uploads of the same
+        filename never clobber each other.
+        """
+        import tempfile
+        from pathlib import Path
+
+        max_mb = _max_upload_mb()
+        file_bytes = await data.read()
+        if len(file_bytes) > max_mb * 1024 * 1024:
+            return {"error": f"Upload is larger than the {max_mb} MB limit; set {MAX_UPLOAD_MB_ENV} to raise it."}
+        filename = _safe_upload_name(data.filename)
+
+        tmp_base = Path(tempfile.gettempdir()) / "tlc-uploads"
+        tmp_base.mkdir(exist_ok=True)
+        dest = Path(tempfile.mkdtemp(dir=tmp_base)) / filename
+        dest.write_bytes(file_bytes)
+
+        return {"path": str(dest), "filename": filename}
+
+    return [browse_filesystem, upload_temp]