Lowers the barrier for sister sites to build their own plugins.
Generated output satisfies the framework contract out of the box.
CLI command (shopdb/plugins/cli.py):
- `flask plugin new <name> --description "..."` generates a plugin
skeleton under plugins/<name>/. Validates the name against
CONTRIBUTING.md rules (lowercase letters/digits only, no
underscores or hyphens, not in the reserved list) and refuses to
overwrite existing plugins unless --overwrite is passed.
- Output prints the next steps (install, migrate, test).
Scaffolder (shopdb/plugins/scaffolder.py):
- validate_name: enforces the naming rules
- pascal_case: lowercase-to-PascalCase for class names
- scaffold_plugin: copies templates with string.Template
substitution. Three placeholders: $name, $Name, $description.
Files with `model.py` in the path get renamed to <name>.py.
Templates (shopdb/plugins/templates/):
- manifest.json.tmpl: name, version 0.1.0, description, core_version
range >=0.1.0,<1.0.0 (broad enough to survive minor framework bumps)
- plugin.py.tmpl: <Name>Plugin class extending BasePlugin with all
required hooks implemented (meta from manifest, get_blueprint
returning the bp, get_models returning the example model). Includes
on_install hook that seeds the AssetType row.
- models/__init__.py.tmpl + models/model.py.tmpl: Asset extension
table keyed by assetid with one example field. TODO comment marks
it as a placeholder.
- api/__init__.py.tmpl + api/routes.py.tmpl: Blueprint with list and
detail endpoints using the framework's pagination + response helpers.
- schemas/__init__.py.tmpl: marshmallow schema stub.
- tests/__init__.py.tmpl + tests/test_plugin.py.tmpl: smoke tests
asserting plugin loads, get_blueprint returns Blueprint, get_models
returns at least one model.
- README.md.tmpl: one-pager for plugin authors with common edits and
next-step references.
Canary tests (tests/test_plugin_scaffold.py):
- 14 tests asserting the scaffold output passes contract checks.
- Validates name rules (lowercase, reserved, hyphens, digits, etc.)
- Verifies all expected files generated, manifest fields present.
- Loads the generated plugin via PluginLoader (spec_from_file_location
bypasses the real `plugins` package shadowing).
- Asserts subclasses BasePlugin, get_blueprint returns Blueprint,
get_models returns model with __tablename__.
- Module-scoped fixture; cleans up sys.modules + SQLAlchemy metadata
on teardown to avoid cross-test contamination.
Quickstart docs (docs/PLUGIN-QUICKSTART.md):
- 30-minute walkthrough: scaffold -> edit model -> add routes ->
install -> verify -> add hooks. Cross-links to PLUGIN-HOOKS.md and
the ADRs. Includes common-errors table.
Test count: 87 -> 101 passing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hardens the plugin framework so sister-site adoption is safe.
Loader rewrite (shopdb/plugins/loader.py):
- Reads manifest.json directly. Dependency sort and version checks
no longer instantiate plugin classes (avoids __init__ side effects).
- Fail-loud policy: in dev/test (DEBUG or TESTING true), plugin
errors re-raise. In production, errors log with full context and
the plugin is excluded from registration. Framework keeps booting.
- Contract-version range check via packaging.SpecifierSet. Plugin's
manifest.core_version must include the framework's
__contract_version__ or load fails per the policy above.
- Manifest validation: required fields (name, version, description),
name matches directory, JSON parseable.
Exceptions (shopdb/exceptions.py):
- PluginNotFoundError, PluginContractError, PluginVersionError,
PluginDependencyError. Specific types replace generic Exception
swallowing.
Auto-register core blueprints (shopdb/__init__.py):
- CORE_BLUEPRINT_NAMES tuple drives registration. Adding a core
resource is one entry, not three lines (import + register call).
- Replaces 27 hand-coded register_blueprint calls.
- Asserts each blueprint is exported by shopdb.core.api at boot.
Public API namespace (shopdb/api/__init__.py):
- audit_log: thin wrapper over AuditLog.log() with stable signature.
- resolve_asset_position: implements ADR-001 position resolution
(asset > related > location). Asset.mapx/mapy and
AssetRelationship.inheritsposition columns are part of the locked
contract surface but not yet in models; helper degrades gracefully
to location-only fallback until the migration lands.
BasePlugin helpers (shopdb/plugins/base.py):
- get_setting(key, default), set_setting(key, value, ...). Settings
namespaced as plugin.<pluginname>.<key> so two plugins can use the
same key without colliding.
Manifest version compatibility (plugins/*/manifest.json):
- Bumped core_version from ">=1.0.0" to ">=0.1.0,<1.0.0" so all
bundled plugins satisfy the new range check.
Contract version bump (shopdb/__init__.py):
- 0.1.0 -> 0.2.0. Additive surface change (Setting helpers,
shopdb.api namespace) per ADR-002 minor-bump rules.
Tests (tests/test_plugin_loader.py, tests/test_api_namespace.py):
- 13 loader tests: manifest validation failures, version range
checks, plugin.py import errors, strict-vs-isolate behavior under
TESTING vs production-like config, manifest-first dependency sort.
- 8 api-namespace tests: audit_log roundtrip, resolve position
fallback chain, plugin.get_setting/set_setting roundtrip with
per-plugin namespacing.
Test count: 66 -> 87 passing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Locks the public surface plugin authors at sister sites depend on.
Contract version (shopdb/__init__.py):
- __contract_version__ = '0.1.0'. Per ADR-002, plugins declare a
compatible range in manifest.json `core_version`. Pre-1.0 signals
the contract is still settling; sister sites should pin tightly.
BasePlugin hook changes (shopdb/plugins/base.py):
- Add get_collector_schema() per ADR-006. Returns JSON Schema (with
identityfield + fields) describing the payload of an external
collector pushing to /api/collector/<pluginname>. Defaults to None
(no auto-registered endpoint).
- Remove get_event_handlers(). Event bus deferred indefinitely per
ADR-001 (no real use case yet; add via new ADR if it appears).
Hook reference (docs/PLUGIN-HOOKS.md):
- Canonical reference for the contract: required hooks (meta,
get_blueprint, get_models), optional hooks (init_app,
get_cli_commands, get_services, get_dashboard_widgets,
get_navigation_items, get_searchable_fields, get_collector_schema),
lifecycle hooks (on_install, on_uninstall, on_enable, on_disable),
helpers exposed in shopdb.api (audit_log, Setting,
resolve_asset_position).
- Versioning rules + change-classification guidance.
Compliance tests (tests/test_plugin_contract.py):
- 8 distinct contract assertions parametrized over 6 bundled plugins
(computers, equipment, network, notifications, printers, usb).
- Asserts: subclasses BasePlugin; manifest has required fields; meta
returns valid PluginMeta; get_blueprint returns Blueprint or None;
get_models returns model classes; get_collector_schema returns
None or {identityfield, fields}; get_navigation_items and
get_searchable_fields return list.
- Plus 3 framework-level: __contract_version__ is valid semver,
get_event_handlers absent, get_collector_schema present.
Test count: 15 -> 66 passing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Establishes the safety net required before any structural refactor.
Tests (tests/):
- conftest.py rewritten for Flask-SQLAlchemy 3.x (drop-recreate per
test, StaticPool-shared in-memory SQLite, admin_user + auth_headers
fixtures). Removes deprecated db.create_scoped_session pattern.
- test_smoke.py: 8 baseline tests (app boot, JWT login valid+invalid,
protected routes, paginated response shape, plugin auto-discovery).
- test_security_config.py: 7 tests pinning ProductionConfig.validate
failure modes (missing/dev SECRET_KEY, missing JWT_SECRET_KEY,
missing DATABASE_URL, wildcard CORS, empty CORS) and one happy-path.
Production hardening (shopdb/config.py, shopdb/__init__.py):
- ProductionConfig.validate() raises ConfigError on missing or
insecure SECRET_KEY, JWT_SECRET_KEY, DATABASE_URL, CORS_ORIGINS.
No silent fallback to dev defaults in production.
- create_app invokes validate() when config_name == 'production'.
- CORS_ORIGINS default no longer wildcard; defaults to localhost
Vite dev origin.
- Drop os.path.exists probe in serve_frontend (path-traversal risk
surface). send_from_directory handles safe-join + 404 itself.
- Replace User.query.get with db.session.get (SQLAlchemy 2.0 API).
TestingConfig (shopdb/config.py):
- Add StaticPool + check_same_thread connect_args so SQLite in-memory
is shared across the test session.
Index dedup (plugins/printers/models/printer_extension.py):
- Rename idx_printer_windowsname -> idx_printerdata_windowsname.
Two model classes (Printer, PrinterData) declared the same index
name; SQLite enforces global index uniqueness even across tables.
Per CONTRIBUTING.md naming convention, indexes follow
idx_<table>_<column>.
Dependency pinning (requirements.in, requirements.txt):
- requirements.in holds the loose source pins (the human-edited file).
- requirements.txt is now a uv-compiled lockfile (every transitive
dep pinned to an exact version). Reproducible builds. Run
`uv pip compile requirements.in -o requirements.txt` to refresh.
Test count: 0 -> 15 passing. All naming/style checks still green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Flask backend with Vue 3 frontend for shop floor machine management.
Includes database schema export for MySQL shopdb_flask database.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
