Files

cproudlock 534f179ee6 Make main the lean product a site receives

main was 16 days and 259 commits behind the line the product is actually built
on, at contract 0.30.0 against 0.35.0, with no per-PC credential code at all. It
was neither current nor curated - just stale. This brings it forward and, at the
same time, makes it mean something: main is what a receiving site installs, and
nothing else.

WHAT IT CARRIES. Twelve plugins - backups, computers, endpoints, guides,
knowledgebase, machines, network, notifications, printers, slides, tools,
warranty - plus applications, which is manifest-less core and always ships. The
only manifest dependency inside that set is endpoints on computers, and both are
in it, so the closure is self-contained.

WHAT IT DOES NOT. employees, geenforce, measuringtools, printedparts and usb
stay on the site line. So do the Windows installer tree, the VM rehearsal
helpers, the agent tooling config, one site's data loader, the internal audit
and findings records, and the planner spreadsheet. 1,135 tracked files against
1,438.

A REMOVAL THAT BREAKS THE APP IS NOT A REMOVAL, and two nearly shipped:

deploy/site-profile-universal.json still named all seventeen plugins. It is the
file docs/DEPLOY.md tells a site to provision from, so a fresh install would
have failed at `flask plugin apply-profile` with PluginError - the first thing a
receiving site does, broken by the branch meant to serve them. It now names the
twelve that exist, and its comment says the two must agree.

agent/ was never refreshed. Whoever populated this branch copied shopdb/,
plugins/, frontend/ and tests/ from the site line and left the agent tree at its
September state: 22 C# and PowerShell sources missing, including AgentCredentials,
EnrollmentService, AgentHttpFactory and the fleet-alert client, plus one file the
site line had deleted still present. The old tree is internally consistent, so it
compiles, and nothing in CI builds it - every gate was green over a server that
speaks enrollment and per-PC credentials to a bundled agent source that cannot.
Resynced whole.

DECISIONS THIS ENCODES, rather than defers:

- The plugin-authoring lab builds printedparts, whose manifest depends on
  employees, so it could not stay. The lab remains on the site line and main
  ships no build-along tutorial. That is a real loss for an adopting developer
  and is recorded here rather than discovered later.
- Recognition, Training and Recertification notifications are no longer seeded.
  Each splits one notification into a card per employee and renders a photo,
  which needs a plugin this branch does not bundle. Seeding them would offer an
  author a type that cannot resolve anybody. A site that installs employees gets
  them from that plugin's own seed.
- Windows/IIS is documented as the legacy path throughout, and the README leads
  with Docker, because that is what a receiving site gets.

The API description is regenerated for THIS branch - 347 paths and 483
operations, down from 415 and 573 - so the published contract describes what is
here rather than what the site line serves. docs/CONFIG.md lost the two
measuring-tool label keys the code no longer declares, which two lanes had
decided opposite ways.

Suite: 3124 passed, 6 skipped. Naming and style gates pass. The docs gates run
rather than skip, and every index line count is derived from the file it names.

2026-09-19 11:24:40 -04:00

10 KiB

Raw Permalink Blame History

Plugins

shopdb-flask is a framework. The plugins listed here are the pieces other GE Aerospace facilities can install, build, or skip per ADR-003. Bundled plugins ship in the framework repo. External plugins live in their own repos and drop into <repo>/plugins/<name>/ at install time.

Bundled (ship with the framework)

These plugins are in plugins/ in this repo. Enable per site with flask plugin install <name>. None of them ships default_enabled: false, so the shelf and the catalog are the same list here: a site turns one on rather than fetching it. PROJECT-MAP carries their versions and migration heads, generated from the code.

Plugin	Tracks	Notes
`machines`	Manufacturing machinery: 5-axis mills, lathes, broachers, heat treatment ovens, and metrology instruments	Manually entered. Metrology instruments are machines here, not a class of their own - see ADR-018. Subtype tables for FOCAS / CLM / MTConnect controller protocols (planned).
`computers`	Shop-floor PCs and engineering workstations	Fed by the PXE pipeline collector per ADR-006.
`printers`	Network and shop-floor printers	Public installer map page + fleet install contract (`/api/printers/install-list`, `/pc-default`, `/install-batch`; see PRINTER-INSTALLER.md). Optional Zabbix integration for supply tracking. Legacy `PrinterData` retiring per ADR-001.
`network`	Switches, routers, access points, IDFs as locations	Asset-only; cleanest of the bundled set.
`notifications`	Shop-floor notifications, recognitions, kiosk feed	Used by `ShopfloorDashboard.vue`.
`knowledgebase`	Knowledge Base articles linking to external resources	Lightweight article store.
`slides`	Slides for the lobby display and shop-floor screensaver	Upload / reorder / delete per surface. Management gated on the `slides.manage` permission, grantable to non-admin curators; display routes are public.
`tools`	Technician utilities: barcode and QR label generation, unit conversions, Secure Send	Mostly browser-side by design, so an air-gapped bench gets them with no network. Secure Send is the exception and is why this plugin has a blueprint, a table and a migration chain: see SECURE-SEND.md.
`warranty`	Asset warranty tracking	Manual entry now, Dell / Lenovo / HP provider lookups later. Derived coverage status with report buckets.
`guides`	Step-by-step procedures written in ShopDB: typed blocks, pasted screenshots, live checkboxes, tags, drafts and revision history	Content is stored as typed blocks rather than markup, so the same guide renders to screen, dark mode and paper. Readers see the PUBLISHED revision only - a technician following a procedure must not have it change under them mid-task. Checkbox ticks are per-viewer and never edit the guide. See GUIDES.md.
`endpoints`	Live endpoint telemetry for shop-floor PCs: liveness, services, processes, inventory, and curated Windows event records, reported by the ShopDB agent	Depends on `computers` - an endpoint is telemetry ABOUT a PC asset, never a second record of it. Adds the Fleet console plus the live panels on a PC's detail page. Four separate permissions: `endpoints.view` to read, `endpoints.fleet` for the fleet-wide console, `endpoints.command` to act on one endpoint, and `endpoints.restart` for a reboot. They are split because read access is grantable to guests and the command channel is not. Ingest is not a route in this plugin: agent reports arrive on the generic collector route and authorize on a service token scoped `collector.ingest.endpoints`, not a user JWT, per ADR-006. That scope doubles as the kill switch for the agent key. See FLEET-ARCHITECTURE.md.
`backups`	Per-asset configuration backups with revision history: NTLARS/DNC registry and part marker	Kind-pluggable per BACKUP-KINDS.md; a kind is one class in `services/registry.py`. Parseable kinds store a JSON projection and re-render to the native format on download; opaque vendor formats stay on the SFLD share with ShopDB holding metadata and the UNC pointer. Fed by the collector, so ingest authorizes on a `collector.ingest` service token, not a user JWT. `backups.view` and `backups.download` are separate permissions because a `.reg` is a restorable artifact. Not to be confused with BACKUP-RESTORE.md, which is the ShopDB database itself.

Plugin permissions

Plugins may register their own permissions (for example slides.manage). Admins implicitly hold them; grant them to specific roles or users to delegate curation without admin. Each plugin's registered permissions appear in its plugin.py get_permissions().

Building your own

Guides:

PLUGIN-HOOKS.md - the contract, and the only page that defines it: every hook, every manifest field, every importable name.
PLUGIN-QUICKSTART.md - start here: generate, customize, install and test a plugin in about 30 minutes.
PLUGIN-GUIDE.md - the conventions and traps of a real plugin, and the checklist to walk before calling one done.
PLUGIN-EXTERNAL-REPO.md - developing a plugin in its own repo per ADR-003: repo layout, symlink dev workflow, core_version pinning, and the CI harness.
PLUGIN-SIGNING.md - packaging a plugin as a signed artifact and trusting it at a site.
CONTRACT-STABILITY.md - how much of the contract is settled, and how tightly to pin.

The contract is locked in ADR-001 and versioned per ADR-002.

Quick path:

flask plugin new cameras --description "Tracks shop-floor surveillance cameras"
# edit plugins/cameras/models/cameras.py with your fields
flask plugin install cameras

Migrations (per-plugin chains)

This is the one place the anchor-vs-baseline rule is written down; other pages link here.

Each plugin that owns tables carries its own Alembic chain under plugins/<name>/migrations/, with a per-plugin version table alembic_version_<name> independent of the core alembic_version. Ownership is split at a fixed cutover (see ADR-008):

The core chain (flask db upgrade) created every table that existed through its head, including the bundled-plugin tables. Each bundled plugin's 0001 migration is a stamp-only no-op anchor recording that fact.
From the cutover forward, a change to a plugin's schema lands as plugins/<name>/migrations/versions/000N_*.py, never in the core chain. The core chain is reserved for core tables.
A plugin built AFTER the cutover (endpoints and guides are the bundled examples), and every plugin built from now on, is different: the core chain never created its tables, so its 0001 is a REAL baseline that creates them, not a no-op anchor.

Deploys and upgrades run flask db upgrade then flask plugin upgrade-all. upgrade-all stamps every plugin anchor and applies any later plugin migrations; it is idempotent. The registry (instance/plugins.json) records which revisions each plugin has applied in migrations_applied.

Distribution conventions

For sister-site plugins (per ADR-003):

Plugin lives in its own git repo: <git-host>/<your-site>/<pluginname>
Adopting site clones or symlinks into their <repo>/plugins/<name>/
Plugin manifest declares core_version range matching the framework version they target
Plugin readme explains: what it tracks, who maintains it, where to file issues

Lean per-site builds

A site ships only the plugins it chose; a site that never wants warranty / guides / network never carries that code (see ADR-013 and ADR-014). Three layers make a build lean:

Backend code - scripts/build-site.sh <profile> stages shopdb/core plus only the chosen plugins' directories (and their hard-dependency closure). A plugin a site did not choose is absent from the backend tree.
Frontend code - SITE_PLUGINS=machines,printers npm run build (via scripts/stage-frontend.mjs) stages only those plugins' frontend/ dirs and codegens the route table. Exception: a plugins/<name>/frontend/ dir with no manifest.json is a CORE feature (e.g. applications), not a per-site plugin, and is ALWAYS staged regardless of SITE_PLUGINS - otherwise a lean build would lose a core page.
Database - the shared core Alembic baseline creates every plugin's tables, so a lean site provisions them and then drops the ones it does not use with flask plugin prune-schema (ADR-014). Run it once at provisioning, after flask db upgrade and flask plugin upgrade-all; see DEPLOY.md.

Menus follow the build, not a plugin flag. The sidebar nav, the settings rail, and the Displays links all gate on whether the target route was actually staged into this build (the router's own route table), not on a registry "enabled" flag. So a lean site never shows a menu entry that dead-ends on a blank page - an omitted plugin's nav item, settings cards, and kiosk links all disappear together. Shopfloor Dashboard is a core view but is gated on the notifications plugin (its only data source), so it drops when notifications is not in the build.

Naming policy

Plugin names follow the framework's naming convention (lowercase concatenated, no underscores or dashes; full words preferred over acronyms). See CONTRIBUTING.md. Plugin name collisions across sites are not enforced; the convention recommends prefixing site-specific plugins with the site code (e.g. sitecode-shippingstation) when there is risk of overlap.

10 KiB Raw Permalink Blame History