ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add frontend integration checklist and docs-drift guard
All checks were successful
CI / backend (push) Successful in 24s
Details
CI / naming (push) Successful in 1s
Details
CI / frontend (push) Successful in 7s
Details

Browse Source 
PLUGIN-QUICKSTART Step 7 is now a concrete 7-item checklist (view
conventions, route auto-discovery + ADR-009 gating meta, api client
shape, nav/report hooks, settings auto-nesting, verification).

New tests/test_docs_contract.py introspects BasePlugin and fails CI when
a public hook is missing from PLUGIN-HOOKS.md or the documented contract
version drifts - it immediately caught two undocumented hooks
(get_provisioning_note, get_config_schema), now documented.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
cproudlock
2026-07-11 10:14:25 -04:00
parent 54c4c808cc
commit 94f852a1c8
3 changed files with 136 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/PLUGIN-HOOKS.md
View File

@@ -216,6 +216,50 @@ Consumed by `GET /api/reports`, which merges plugin cards after the static core
reports sorted into category groups by the frontend (disabled plugins are
skipped; a broken plugin is isolated in prod, re-raised in dev/test).
### `get_provisioning_note() -> Optional[Dict]`
Transparency note the setup wizard shows the moment a site checks this plugin
during setup. Return `None` (the default) for plugins that need no special
setup. Plugins that create extra tables beyond their asset-extension table
(e.g. a self-hosted directory) return:
```python
class EmployeesPlugin(BasePlugin):
def get_provisioning_note(self):
return {
'tables': ['directoryemployees'],
'note': 'Creates a local employee directory table in the shopdb database.',
'docs': 'plugins/employees/README.md',
}
```
### `get_config_schema() -> List[Dict]`
Declares the config fields this plugin needs, so the setup wizard can prompt
for them. Return `[]` (the default) if the plugin needs no configuration.
Each field is a dict:
| Key | Meaning |
|-----|---------|
| `key` | the Setting key (non-secret) it maps to |
| `label` | human label shown in the wizard |
| `type` | `'text'` / `'number'` / `'password'` |
| `secret` | `True` for credentials; NOT stored in the DB - the wizard emits an `.env` line for the operator instead |
| `envvar` | (secret only) the `.env` variable name to emit |
| `default` | optional placeholder |
| `help` | optional hint |
```python
class PrintersPlugin(BasePlugin):
def get_config_schema(self):
return [
{'key': 'zabbix_url', 'label': 'Zabbix URL', 'type': 'text',
'help': 'Base URL of the Zabbix server for supply lookups'},
{'key': 'zabbix_token', 'label': 'Zabbix API token', 'type': 'password',
'secret': True, 'envvar': 'ZABBIX_TOKEN'},
]
```
### `get_collector_schema() -> Optional[Dict]`
Declares the JSON Schema for an external collector pushing to `/api/collector/<pluginname>`. See [ADR-006](../docs/adr/ADR-006-collector-contract.md) for the contract.