shopdb-flask

Files

cproudlock 7b79a444b8 Scaffold a plugin's frontend into the plugin, so it can be pruned

`flask plugin new` wrote views to frontend/src/views/<name>/ and a route file
to frontend/src/router/routes/<name>.js. Every one of the 16 bundled plugins
keeps its frontend in plugins/<name>/frontend/ instead, staged into
.plugins-staged by stage-frontend.mjs and aggregated into routes.gen.js.

It was not visibly broken, which is why it lasted: the router still globs
./routes/*.js during the Phase 4 dual-location transition, so a scaffolded
plugin's pages loaded. What a new plugin author silently lost was ADR-013 lean
builds. Pruning works off the staged tree, so a frontend in the core tree
cannot be excluded from a site build, and deleting the plugin strands its
views behind.

The templates for the correct layout already existed; only the output paths
were wrong. Also fixed the imports they carry: core imports now use the @
alias (@/api, @/components/...), which resolves both before and after staging,
where the previous ../../api was correct only in the old location. Sibling
views stay relative and travel with the route file.

frontend_dir is gone from scaffold_plugin. There is no second output tree to
point at, and a plugin developed in its own repo now gets the same frontend as
a bundled one rather than being skipped.

Proven end to end: scaffolded a throwaway plugin, confirmed it stages, builds
real chunks, and that SITE_PLUGINS=network prunes it, which is what the old
layout could not do.

2026-08-24 14:05:15 -04:00

api

Enforce plugin contract purity: single import surface via shopdb.api

2026-06-26 16:45:06 -04:00

frontend

Scaffold a plugin's frontend into the plugin, so it can be pruned

2026-08-24 14:05:15 -04:00

models

Enforce plugin contract purity: single import surface via shopdb.api

2026-06-26 16:45:06 -04:00

schemas

Phase 4: plugin scaffolding (flask plugin new) with canary tests

2026-05-08 17:13:46 -04:00

tests

Phase 4: plugin scaffolding (flask plugin new) with canary tests

2026-05-08 17:13:46 -04:00

__init__.py.tmpl

Phase 4: plugin scaffolding (flask plugin new) with canary tests

2026-05-08 17:13:46 -04:00

manifest.json.tmpl

Phase 4: plugin scaffolding (flask plugin new) with canary tests

2026-05-08 17:13:46 -04:00

plugin.py.tmpl

Enforce plugin contract purity: single import surface via shopdb.api

2026-06-26 16:45:06 -04:00

README.md.tmpl

Phase 4: plugin scaffolding (flask plugin new) with canary tests

2026-05-08 17:13:46 -04:00

README.md.tmpl

# $Name plugin

$description

This plugin was generated by `flask plugin new $name`. It satisfies the framework contract out of the box. Replace the example model and routes with your domain.

## What's here

- `plugin.py` - the `${Name}Plugin` class extending `BasePlugin`. Edit `init_app` for custom setup, `on_install` to seed reference data.
- `models/$name.py` - example Asset extension table. Replace `examplefield` with your domain fields.
- `api/routes.py` - example list and detail endpoints. Add CRUD as needed.
- `schemas/__init__.py` - marshmallow schema stub for request/response validation.
- `tests/test_plugin.py` - smoke tests asserting contract compliance.
- `manifest.json` - plugin metadata. Bump `version` on changes; keep `core_version` range broad.

## Common edits

| You want to... | Do this |
|---|---|
| Add a hook (search, navigation, dashboard widget) | Override the method in `${Name}Plugin`. See `docs/PLUGIN-HOOKS.md`. |
| Accept external collector data | Override `get_collector_schema()` to return a JSON Schema. See ADR-006. |
| Add another model | Create `models/<other>.py`, export it in `models/__init__.py`, return it in `get_models()`. |
| Add a CLI command | Override `get_cli_commands()` returning a list of Click commands. |

## Frontend

Vue components for this plugin live under `frontend/src/views/$name/` (per project convention). Backend scaffolding does not generate frontend yet; copy from an existing plugin's view files (e.g., `frontend/src/views/network/`) as a starting point.

## Install and run

```bash
flask plugin install $name
flask db migrate -m "Add $name plugin tables"
flask db upgrade
pytest plugins/$name/tests/
```

## References

- `docs/PLUGIN-HOOKS.md` - canonical hook reference
- `docs/PLUGIN-QUICKSTART.md` - 30-minute walkthrough
- `migrations/adr/ADR-001-asset-as-platform-contract.md` - the platform contract
- `migrations/adr/ADR-002-plugin-versioning.md` - versioning rules