f4b2ed7613
Four changes from looking at the built page. ACTIONS HELD ONE CARD. Tracked services was the only thing in it, and it was the wrong split anyway: a service row reads as state first and a Start/Stop second, so separating the buttons from the state they act on made a tab that answered no question on its own. Services move to Metrics, beside the rest of what the endpoint reports, and the group is gone from the contract. WIDE PANELS SPAN, THEY DO NOT SCROLL. Network interfaces carries adapter, address, MAC, speed and state; at half page width in the two-column flow it either squeezed every cell to three lines or offered a horizontal scrollbar. A scrollbar for data that just needs room is a layout failure. Table panels now take column-span, which is the multi-column layout's own answer, so short fact cards stay two-up around them. The wrapper keeps overflow-x only as a floor for a genuinely narrow viewport. SOFTWARE AND ACTIVITY RUN FULL WIDTH. Both are single long lists, and a list split into two balanced columns reads as two unrelated lists with no way to tell where the first ended. Details and Metrics keep the two-column flow because they are short cards, which is what that flow is good at. Contract 0.29.0 keeps its number: it is unreleased, and the group vocabulary it introduces has simply lost one value before anybody could depend on it. Scope: product
442 lines
18 KiB
Python
442 lines
18 KiB
Python
"""Base plugin class that all plugins must inherit from."""
|
|
|
|
from abc import ABC, abstractmethod
|
|
from typing import List, Dict, Optional, Type
|
|
from dataclasses import dataclass, field
|
|
from flask import Flask, Blueprint
|
|
|
|
|
|
@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
|
|
core_version: str = ">=0.2.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 (e.g. a self-hosted directory or USB tables), return:
|
|
{
|
|
'tables': ['directoryemployees', ...], # 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_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 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' | 'software' | 'metrics'
|
|
# | '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 -
|
|
an inventory listing, live telemetry, 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
|
|
telemetry first and a Start/Stop second, so they live in 'metrics' with
|
|
the rest of what the endpoint reports. 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.
|
|
"""
|
|
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.
|
|
"""
|
|
return []
|