shopdb-flask/shopdb/plugins/base.py

"""Base plugin class that all plugins must inherit from.

One rule that is not expressible as a method signature, so it lives here where
a plugin author reads it: A PLUGIN MUST NOT HOLD A DB SESSION ACROSS EXTERNAL
I/O. Finish with the database, then make the HTTP call / run the subprocess /
touch the share, then open a fresh session to write the result. Under gevent a
slow external call does not block its worker, but it does pin one of that
worker's pooled database connections for its whole duration, and enough
concurrent greenlets on such a path drain the pool and stall every other
request in the process - the whole site, every plugin, with the CPU idle and
MySQL healthy. See CONTRIBUTING.md ("A plugin must not hold a DB session across
external I/O") for the shape to write, and docker-compose.yml for how the pool
relates to the worker count and to MySQL max_connections.
"""

from abc import ABC, abstractmethod
from typing import List, Dict, Optional, Type
from dataclasses import dataclass, field
from flask import Flask, Blueprint


# Settings hubs whose Vue page actually draws plugin-contributed tabs: it asks
# /api/plugins/settings-routes, keeps the routes whose `hub` matches its own id,
# and registers them with router.addRoute(). Every other hub renders its own
# tabs and nothing else, so a route naming one would be returned by the API and
# never drawn - a tab the author declared correctly that simply does not exist
# for the user. Hubs are added here only when their .vue file gains that code;
# tests/test_core/test_plugin_settings_hubs.py fails if the two drift apart.
SETTINGS_HUBS_WITH_PLUGIN_TABS = ('model-catalog',)


def renderable_settings_routes(plugin_name: str, routes: Optional[List[Dict]],
                               logger) -> List[Dict]:
    """The subset of a plugin's declared settings routes that a hub can draw.

    Anything naming a hub outside SETTINGS_HUBS_WITH_PLUGIN_TABS is dropped and
    logged as an error naming the plugin, the hub and the supported set. The
    declaration is not a crash - the plugin's API, models and pages are all
    fine - so this refuses the dead tab rather than the plugin. The hard stop
    lives in the test suite, where the author still has a chance to fix it.
    """
    kept = []
    for route in routes or []:
        hub = route.get('hub')
        if hub in SETTINGS_HUBS_WITH_PLUGIN_TABS:
            kept.append(route)
            continue
        logger.error(
            "Plugin %s declares settings route '%s' for hub '%s'. No settings "
            "hub page registers plugin tabs for that hub, so the tab would "
            "never render; dropping it. Hubs that support plugin tabs: %s",
            plugin_name, route.get('name'), hub,
            ', '.join(SETTINGS_HUBS_WITH_PLUGIN_TABS))
    return kept


@dataclass
class PluginMeta:
    """Plugin metadata container."""

    name: str
    version: str
    description: str
    author: str = ""
    dependencies: List[str] = field(default_factory=list)
    # Default to the current pre-1.0 contract range; tighten when 1.0 lands
    # 0.20.0: added get_asset_type_descriptor hook (additive, backward-compatible)
    core_version: str = ">=0.20.0,<1.0.0"
    api_prefix: str = None

    def __post_init__(self):
        if self.api_prefix is None:
            self.api_prefix = f"/api/{self.name.replace('_', '-')}"


class BasePlugin(ABC):
    """
    Base class for all ShopDB plugins.

    Plugins must implement:
        - meta: PluginMeta instance
        - get_blueprint(): Return Flask Blueprint for API routes
        - get_models(): Return list of SQLAlchemy model classes

    Optionally implement:
        - init_app(app, db): Custom initialization
        - get_cli_commands(): Return Click commands
        - get_services(): Return service classes
        - on_install(): Called when plugin is installed
        - on_uninstall(): Called when plugin is uninstalled
        - on_enable(): Called when plugin is enabled
        - on_disable(): Called when plugin is disabled
    """

    @property
    @abstractmethod
    def meta(self) -> PluginMeta:
        """Return plugin metadata."""
        pass

    @abstractmethod
    def get_blueprint(self) -> Optional[Blueprint]:
        """Return Flask Blueprint with API routes."""
        pass

    @abstractmethod
    def get_models(self) -> List[Type]:
        """Return list of SQLAlchemy model classes."""
        pass

    def init_app(self, app: Flask, db) -> None:
        """
        Initialize plugin with Flask app.
        Override for custom initialization.
        """
        pass

    def get_cli_commands(self) -> List:
        """Return list of Click command groups/commands."""
        return []

    def get_services(self) -> Dict[str, Type]:
        """Return dict of service name -> service class."""
        return {}

    def get_provisioning_note(self) -> Optional[Dict]:
        """Transparency note shown when a site enables this plugin.

        Return None for plugins that need no special setup. For plugins that
        create extra tables (a revision history, an events log), return:
          {
            'tables': ['backuprevisions', ...],      # created in the shopdb DB
            'note':   'Plain-language what/why.',
            'docs':   'plugins/<name>/README.md',     # where the schema lives
          }
        The setup wizard shows this the moment the plugin is checked.
        """
        return None

    def get_config_schema(self) -> List[Dict]:
        """Declare the config fields this plugin needs, for the setup wizard.

        Each field is a dict:
          key      - the Setting key (non-secret) it maps to
          label    - human label
          type     - 'text' | 'number' | 'password'
          secret   - True for credentials; these are NOT stored in the DB, the
                     wizard emits an .env line for the operator to paste instead
          envvar   - (secret only) the .env variable name to emit
          default  - optional default shown as a placeholder
          help     - optional hint
        Return [] (default) if the plugin needs no configuration.
        """
        return []

    def get_guest_grantable_permissions(self) -> List[str]:
        """Permissions this plugin allows a site to grant to the GUEST role.

        A guest is anyone with no account. EVERY permission of this plugin's
        that a site may grant one has to be named here, reads included.

        Reads used to be automatic: anything ending `.view` or `.read` was
        grantable. That treats a name as a decision, and it went wrong in the
        obvious way - permissions that gated installer bytes, backup payloads
        and a search across the staff directory were all anonymous-grantable
        because of how they were spelled. So the plugin that owns a permission
        now says, having looked at what its routes return.

        Naming one here does not open it. It makes the checkbox available in
        the role grid; a site still has to tick it. Return [] (the default) and
        nothing of this plugin's can be made anonymous.

        The bar for a read: could an anonymous visitor hold this, forever, and
        would the site be content with everything the routes return - every
        column of every serializer, not just the ones the UI happens to show?
        For a write, add that the act can never be attributed to anybody.
        """
        return []

    def get_settings_routes(self) -> List[Dict]:
        """Frontend routes this plugin adds to settings pages.

        Returns a list of route configurations for the plugin's settings pages.
        Each route is a dict with:
          hub      - settings hub to attach to; ONLY a hub named in
                     SETTINGS_HUBS_WITH_PLUGIN_TABS (top of this module) draws
                     plugin tabs. A route for any other hub is dropped by
                     /api/plugins/settings-routes with an error in the log.
          path     - route path relative to hub (e.g. 'operatingsystems')
          name     - unique route name (e.g. 'model-catalog-os')
          tab      - tab label shown in hub UI (e.g. 'Operating Systems')
          component- path to the Vue component AS IT EXISTS IN THE BUILD, i.e.
                     relative to frontend/src, which for a plugin means
                     '.plugins-staged/<name>/views/<Component>.vue' - the copy
                     scripts/stage-frontend.mjs makes of plugins/<name>/frontend

        Example:
          return [{
            'hub': 'model-catalog',
            'path': 'operatingsystems',
            'name': 'model-catalog-os',
            'tab': 'Operating Systems',
            'component': '.plugins-staged/computers/views/OperatingSystemsList.vue'
          }]

        Three constraints the shape of this hook does not show, so read them
        before you rely on it (ADR-019, "Constraints as implemented"):

        1. Declare a hub only if it is in SETTINGS_HUBS_WITH_PLUGIN_TABS. Today
           that is 'model-catalog' alone. The other hubs have no code to draw
           your tab, so the route is accepted and dropped.
        2. Route the page yourself as well, in plugins/<name>/frontend/
           routes.js, and treat THAT as the real route. The hub interpolates
           `component` into a dynamic import with no static file extension,
           which Vite will not rewrite, so the tab loads under `npm run dev`
           and 404s in a production build. A page reachable only through the
           tab is a page nobody can open at a site. Your frontend also has to
           be staged into the build (SITE_PLUGINS decides that), so enabling a
           plugin whose UI was never staged needs a frontend rebuild.
        3. The tab is not a link you can hand out. The hub registers the route
           when it mounts, so the URL resolves only for someone who has already
           been through the parent hub in that page load. Do not link to it
           from an email, a doc, or another page, and do not expect a refresh
           on it to land anywhere.

        Return [] (default) if the plugin adds no settings pages.
        """
        return []

    def get_settings_defaults(self) -> List[Dict]:
        """Declare the Setting rows this plugin owns.

        The framework seeds these at install, at enable, and on every
        `flask plugin upgrade-all`, so a setting added in a later plugin
        version reaches a site that installed an earlier one. Declaring a key
        here is also what tells the settings API which category and type the
        key belongs to, so a save never has to invent one.

        Each entry is a dict:
          key         - the Setting key
          value       - default value (string form)
          valuetype   - 'string' | 'boolean' | 'integer' | 'json'
          category    - grouping the plugin's settings page filters on
          description - what the setting does
          public      - True if an UNAUTHENTICATED caller may read it (kiosk
                        and print pages render before login); default False.
                        Never mark a credential or an integration URL public.
        Return [] (default) if the plugin owns no settings.
        """
        return []

    def get_setting(self, key: str, default=None):
        """Read a plugin-scoped setting from the core Setting store.

        Settings are namespaced by plugin name to avoid collisions
        across plugins. The on-disk key is `plugin.<pluginname>.<key>`.

        Returns the typed value (string, integer, boolean, etc.) or
        the default if not set.
        """
        from shopdb.core.models import Setting
        namespaced_key = f'plugin.{self.meta.name}.{key}'
        return Setting.get(namespaced_key, default)

    def set_setting(self, key: str, value, valuetype: str = 'string',
                    description: str = None) -> None:
        """Write a plugin-scoped setting to the core Setting store.

        Settings are namespaced by plugin name. Persists immediately and
        survives restarts.
        """
        from shopdb.core.models import Setting
        namespaced_key = f'plugin.{self.meta.name}.{key}'
        Setting.set(
            namespaced_key,
            value,
            valuetype=valuetype,
            category=f'plugin.{self.meta.name}',
            description=description,
        )

    def get_collector_schema(self) -> Optional[Dict]:
        """Return JSON Schema describing the collector payload for this plugin.

        Return None if the plugin does not accept collector input.

        See ADR-006 for the contract. The schema must include:
        - 'identityfield': name of the field that uniquely identifies an
          asset across submissions (e.g., 'hostname' for PCs,
          'macaddress' for network devices). Used for idempotent upsert.
        - 'fields': JSON Schema definitions for the rest of the payload.

        Plugins returning a non-None schema have an endpoint at
        /api/collector/<pluginname> auto-registered by the loader.
        """
        return None

    def apply_collector_payload(self, payload: Dict) -> Dict:
        """Idempotently upsert an asset from a validated collector payload.

        Called by the generic /api/collector/<pluginname> endpoint after the
        payload passed schema validation. Plugins that return a schema from
        get_collector_schema must implement this. Return a dict with at least:
        - 'action': 'created' | 'updated' | 'noop'
        - 'assetid': the affected asset id (or None)
        - 'warnings': list[str]
        """
        raise NotImplementedError(
            f"{self.meta.name} declares a collector schema but does not "
            f"implement apply_collector_payload"
        )

    def resolve_agent_credential(self, secret: str) -> Optional[int]:
        """Asset id for an active per-PC agent credential, else None.

        Optional (contract 0.33.0). A plugin that issues endpoint credentials
        answers here so the generic collector can accept them on any schema
        declaring 'acceptsagentcredential'. Called via
        shopdb.api.resolve_agent_credential, which asks enabled plugins and
        takes the first non-None answer.
        """
        return None

    def agent_shared_key_refused(self, hostname: str) -> bool:
        """True when the shared collector key may not report for this hostname.

        Optional (contract 0.33.0). True when the shared key is switched off or
        the hostname's asset holds an active per-PC credential. Called via
        shopdb.api.agent_shared_key_refused, which is True if any enabled
        plugin says so.
        """
        return False

    def on_install(self, app: Flask) -> None:
        """Called when plugin is installed via CLI."""
        pass

    def on_uninstall(self, app: Flask) -> None:
        """Called when plugin is uninstalled via CLI."""
        pass

    def on_enable(self, app: Flask) -> None:
        """Called when plugin is enabled."""
        pass

    def on_disable(self, app: Flask) -> None:
        """Called when plugin is disabled."""
        pass

    def get_dashboard_widgets(self) -> List[Dict]:
        """
        Return dashboard card definitions.

        DATA AND SHAPE, not a component name. The card is drawn by one of core's
        generic renderers; the plugin says what to show, where it comes from and
        how to link it.

        Contract 0.19.0 replaced a shape that named a Vue component per widget.
        That could not survive a lean build - a plugin's component may never be
        staged into the frontend bundle (ADR-013) - and in practice five plugins
        declared widgets pointing at components nobody had written, which
        rendered as nothing at all. It is the same correction ADR-010 already
        made for asset panels.

        Each card: {
            'id': str,          # stable, unique across plugins
            'title': str,       # heading
            'shortname': str,   # optional: label for this card's rows in the
                                # merged queue. A title reads as a header and is
                                # too long as a row badge; defaults to title.
            'endpoint': str,    # API path the card fetches its own data from
            'render': str,      # core renderer: 'exceptions' | 'list' | 'stat'
            'severity': str,    # 'critical' | 'warning' | 'info' - orders cards
            'permission': str,  # card is hidden without it
            'empty': str,       # 'hide' when nothing to report, or empty text
            'position': int,    # order within a severity
            'viewall': str,     # optional route behind the card heading
            'map': dict,        # optional field mapping for the renderer,
                                # e.g. {'title': 'hostname', 'detail': 'entryname'}
        }

        `empty: 'hide'` is not cosmetic. A card that reports "nothing wrong"
        every day teaches people to stop reading the page.
        """
        return []

    def get_navigation_items(self) -> List[Dict]:
        """
        Return navigation menu items.

        Each item: {
            'name': str,
            'icon': str,
            'route': str,
            'position': int,
            'children': []
        }
        """
        return []

    def get_permissions(self) -> List:
        """
        Return the RBAC permissions this plugin owns.

        Each entry is a (name, description, category) tuple, matching the core
        permission catalog shape (dicts with those keys are also accepted):

            [
                ('machines.view',   'View machines',   'machines'),
                ('machines.create', 'Create machines', 'machines'),
                ('machines.edit',   'Edit machines',   'machines'),
                ('machines.delete', 'Delete machines', 'machines'),
            ]

        A plugin owns the permission names its own routes enforce via
        require_permission; core no longer accumulates them. The names must
        follow the naming convention (lowercase dotted, e.g. `machines.edit`).

        Consumed by full_permission_catalog(): core permissions plus every
        ENABLED plugin's get_permissions(). That catalog backs `flask seed
        permissions`, the role-management grid (GET /api/users/permissions),
        and API-token scope validation. Plugin install/enable also seeds the
        plugin's own permissions idempotently.

        Disabled plugins are skipped by the catalog, so their permissions are
        no longer offered for new scope grants or new role assignments. The
        Permission ROWS already in the database are NOT deleted, so roles that
        already reference them keep working until an admin edits the role. A
        broken plugin is isolated in prod and re-raised in dev/test.

        Return [] (the default) if the plugin needs no permissions.
        """
        return []

    def get_reports(self) -> List[Dict]:
        """
        Return report card definitions for the Reports hub.

        Each entry: {
            'id': str,           # stable report id
            'name': str,         # card title
            'description': str,  # one-line blurb
            'category': str,     # grouping key (lowercase)
            # plus EXACTLY ONE of:
            'route': str,        # frontend path for a dedicated report page
            'endpoint': str,     # API endpoint for generic inline rendering
        }

        Consumed by GET /api/reports, which merges these after the static core
        reports. Disabled plugins are skipped by the consumer.
        """
        return []

    def get_settings_cards(self) -> List[Dict]:
        """
        Return settings-catalog card definitions (ADR-010).

        Each card contributes an entry to the settings rail + landing overview
        without a plugin hand-editing the core settingsNav.js catalog.

        Each card: {
            'group':       str,   # rail group title (created if new)
            'to':          str,   # settings route the card links to
            'icon':        str,   # string key, mapped to a Lucide icon core-side
            'title':       str,   # card title
            'description': str,   # one-line blurb
            'position':    int,   # order within the group
        }

        Consumed by GET /api/pluginui/settings-cards, which merges enabled
        plugins' cards into the core catalog. Disabled plugins are skipped;
        a broken plugin is isolated in prod, re-raised in dev/test.
        """
        return []

    def get_asset_panels(self) -> List[Dict]:
        """
        Return asset-detail extension-panel definitions (ADR-010).

        A generic core AssetPanel component renders each panel on the asset
        detail pages whose type matches, fetching the panel's endpoint. This
        replaces hand-composing a plugin panel component into each detail view.

        Each panel: {
            'id':         str,        # stable panel id
            'title':      str,        # panel heading
            'assettypes': List[str],  # AssetType keys it appears on; ['*'] = all
            'endpoint':   str,        # data endpoint (may contain {assetid})
            'render':     str,        # 'keyvalue' | 'table' | 'badge' | 'list'
                                      # ('list' takes a 'map' of title/badge/meta
                                      # keys, rendered generically - see warranty)
            'position':   int,        # order among panels
            'group':      str,        # OPTIONAL. Which tab on the detail page:
                                      # 'details' | 'monitors' | 'software'
                                      # | 'activity'. Omitted means 'details'.
        }

        ON 'group'. The detail pages are tabbed, and a panel says which tab it
        belongs to rather than the page listing panels by id - a page that knew
        its plugins' panels by name would defeat the point of the hook.

        Omitting it is the correct answer for most panels and keeps every
        existing plugin working untouched: an unknown or absent group resolves
        to 'details', which is the tab that holds what an asset IS. Reach for
        another group only when the panel is the thing that tab exists for -
        what is being watched on the box, an inventory listing, or a history
        feed.

        There is deliberately no group for controls. A panel that acts on the
        machine belongs beside the state it acts on: tracked services read as
        state first and a Start/Stop second, so they live in 'monitors' with
        the rest of what is being watched. Splitting the buttons away from
        the state they change made a tab that held one card and answered no
        question on its own.

        Consumed by GET /api/pluginui/asset-panels?assetid=<id>, which returns
        the panels matching that asset's type. Disabled plugins
        are skipped; a broken plugin is isolated in prod, re-raised in dev/test.
        A panel needing bespoke UI is out of scope for the data-only hook.
        """
        return []

    def get_map_overlays(self) -> List[Dict]:
        """
        Return shop-floor map overlay/decoration definitions (ADR-010).

        The map is data-driven off asset types + positions; an overlay adds
        decoration data (a badge or ring on already-placed markers) plus a
        legend entry, without the plugin shipping any map code.

        Each overlay: {
            'id':       str,   # stable overlay id
            'label':    str,   # legend label
            'endpoint': str,   # returns [{assetid, color, label}] to decorate
            'style':    str,   # 'badge' | 'ring'
            'legend':   bool,  # True to add a legend entry
        }

        Consumed by GET /api/pluginui/map-overlays. Disabled plugins are
        skipped; a broken plugin is isolated in prod, re-raised in dev/test.

        No bundled plugin implements this, so the dict above IS the whole
        specification - there is no shipped example to copy. Core's side is
        exercised against a stub in tests/test_core/test_pluginui.py, which is
        also the shortest worked example of a declaration.
        """
        return []

    def get_asset_presentation(self) -> List[Dict]:
        """
        Return asset-type presentation/routing definitions (ADR-010).

        Declares how a plugin-owned asset type renders in global-search rows
        and cross-links: which icon to show and where the detail link points,
        so core never hardcodes a plugin's route or icon.

        Each entry: {
            'assettype': str,  # AssetType.assettype key the plugin owns
            'icon':      str,  # string key, mapped to a Lucide icon core-side
            'label':     str,  # human label for the type
            'route':     str,  # detail-route pattern (may contain {assetid})
        }

        Consumed by GET /api/pluginui/asset-presentation. Disabled plugins are
        skipped; a broken plugin is isolated in prod, re-raised in dev/test.

        No bundled plugin implements this either; same note as get_map_overlays
        above. With nothing declaring one, the route returns [] and core falls
        back to its legacy id-keyed route map in shopdb/core/api/search.py.
        """
        return []

    def get_asset_type_descriptor(self) -> Optional[Dict]:
        """Return subtype management descriptor for this plugin's asset type.

        Declares how to CRUD the plugin's subtype table (printertypes,
        machinetypes, etc.) so core can render a generic CRUD UI without
        importing the plugin's models or views. Return None if the plugin
        has no subtype table.

        Contract (all keys required if returning non-None):
          {
            'assettype': str,              # matches assettypes.assettype
            'subtype_endpoint': str,       # API path WITHOUT /api prefix (e.g., '/printers/types')
            'subtype_id_field': str,       # PK field name (e.g., 'printertypeid')
            'subtype_label_field': str,    # Display name field (e.g., 'printertype')
            'subtype_description_field': str,  # Description field
            'subtype_color_field': str,    # Color field for map markers
            'optional_tabs': List[str],    # Plugin-specific tabs (e.g., ['supplies'])
            'edit_permission': str,        # Required permission (e.g., 'printers.manage')
          }

        The endpoint must support:
          - GET    (list) ?active=true/false for pagination
          - GET    /{id} for single record
          - POST   (create)
          - PUT    /{id} (update)
          - DELETE /{id}

        Payload fields:
          - {subtype_label_field}: required string
          - {subtype_description_field}: optional text
          - {subtype_color_field}: optional string (CSS color)
          - isactive: optional boolean (default True)

        Consumed by GET /api/pluginui/asset-type-descriptors. Disabled
        plugins are skipped; a broken plugin is isolated in prod, re-raised
        in dev/test.
        """
        return None