Merge the wilm delivery work into main

Ben Baker's installed-software collection, software delivery (run_script and
update_app), agentless adoption tool and command-queue hardening, with his
authorship preserved.

Reviewed before promotion. Fixed: the endpoints plugin tests were never collected
by pytest, the SBOM snapshot table's key would exhaust on MySQL, ingest did not
truncate two columns strict MySQL would reject, and update_app's version branch
pinned a digest for a file that route never serves. Agent packaging moved off
require_role('admin') onto a new endpoints.agentpackage permission.

Contract 0.27.0. Full suite 2231, frontend 314.

tests/test_core/test_appversion_delivery.py

@@ -0,0 +1,42 @@
+"""AppVersion installer-delivery metadata: sha256 + silentargs.
+
+These two per-version fields feed the endpoint installer push: sha256 pins the
+exact bytes the agent fetches, and silentargs carries the version's unattended-
+install switches. The API must accept and echo both, and the model must
+serialize them.
+"""
+
+
+def _create_app(client, auth_headers, appname='DeliveryApp'):
+    resp = client.post('/api/applications',
+                       json={'appname': appname, 'isinstallable': True},
+                       headers=auth_headers)
+    return resp.get_json()['data']['appid']
+
+
+def test_create_version_accepts_and_echoes_delivery_metadata(client, db, auth_headers):
+    """POST versions with sha256 + silentargs; the response carries both back."""
+    appid = _create_app(client, auth_headers)
+    digest = 'a' * 64
+    resp = client.post(f'/api/applications/{appid}/versions',
+                       json={'version': '1.2.3',
+                             'sha256': digest,
+                             'silentargs': '/S /v/qn'},
+                       headers=auth_headers)
+    assert resp.status_code == 201
+    data = resp.get_json()['data']
+    assert data['sha256'] == digest
+    assert data['silentargs'] == '/S /v/qn'
+
+
+def test_version_delivery_metadata_defaults_to_null(client, db, auth_headers):
+    """A version created without delivery metadata serializes both as null,
+    so a version that predates the push feature reads cleanly."""
+    appid = _create_app(client, auth_headers, appname='NoMetaApp')
+    resp = client.post(f'/api/applications/{appid}/versions',
+                       json={'version': '0.9.0'},
+                       headers=auth_headers)
+    assert resp.status_code == 201
+    data = resp.get_json()['data']
+    assert data['sha256'] is None
+    assert data['silentargs'] is None

tests/test_core/test_public_read_surface.py

@@ -83,6 +83,15 @@ PUBLIC_ENDPOINTS = {
     # requesting user. Same reasoning as endpoints.report_command_result in
     # tests/test_core/test_authz.py.
     'endpoints.claim_next_command',
+
+    # The endpoint agent downloads an installer package for an update_app
+    # command. Authenticated inside the handler by the endpoints collector API
+    # key - the same shape as claim_next_command - because a bay has no user
+    # session. Queueing the update_app command is the actual authority and stays
+    # gated on endpoints.deploy, audited with the requesting user.
+    'endpoints.download_app_package',
+    'endpoints.download_app_package_by_app',
+    'endpoints.download_script_body',
 }
 
 # Reads that need a LOGIN but no named permission, because the handler decides

tests/test_docs_publishable.py

@@ -28,9 +28,15 @@ DOCS = REPO / 'docs'
 # test_there_are_docs_to_check exists to catch. Distinguishing the two matters:
 # collapsing them either breaks CI on the published mirror (this module failed
 # there for exactly this reason) or quietly disables the guard everywhere.
+#
+# The test is docs/*.md PROSE, not docs/ existing. docs/openapi.json is tracked
+# so the app can serve it at runtime, which means docs/ exists even on the
+# published mirror - keying off the directory made this module run there against
+# a prose-less tree and fail. A published checkout is one with no authored
+# prose, matching the canonical definition in scripts/check-gates-ran.sh.
 pytestmark = pytest.mark.skipif(
-    not DOCS.is_dir(),
-    reason='no docs/ in this checkout - it is excluded from publication and lives in the wiki')
+    not any(DOCS.glob('*.md')),
+    reason='no docs/ prose in this checkout - it is excluded from publication and lives in the wiki')
 
 # Kept in step with the scrub list in tools/export-github.sh. Two mechanisms for
 # one rule is not ideal, but the export scrubs a tree it is about to commit while

tests/test_docs_versions.py

@@ -23,9 +23,14 @@ import pytest
 REPO = Path(__file__).resolve().parents[1]
 DOCS = REPO / 'docs'
 
+# docs/openapi.json is tracked so the app can serve it at runtime, so docs/
+# exists even on the published mirror where the authored prose is not. Keying
+# the skip off the directory made this module run on the mirror against a
+# prose-less tree and fail. A published checkout is one with no docs/*.md prose,
+# matching the canonical definition in scripts/check-gates-ran.sh.
 pytestmark = pytest.mark.skipif(
-    not DOCS.is_dir(),
-    reason='no docs/ in this checkout - it is excluded from publication')
+    not any(DOCS.glob('*.md')),
+    reason='no docs/ prose in this checkout - it is excluded from publication')
 
 # The map is generated and the changelog records history; both are allowed to
 # carry literal versions. CONTRACT-STABILITY's table is a history of what each

tests/test_endpoint_command_reaper.py

@@ -0,0 +1,69 @@
+"""Regression tests for the endpoint command-queue staleness reaper.
+
+A claimed command whose agent never reports back (agent killed, uninstalled, or
+offline mid-flight) would otherwise pin the at-most-one-in-flight queue forever,
+so every operator action against that endpoint returns 409 "already in flight".
+The enqueue path reaps such rows to STATUS_EXPIRED so the queue self-heals.
+"""
+
+from datetime import timedelta
+
+
+def test_reap_stale_commands_frees_a_wedged_queue(db):
+    from plugins.endpoints.models import EndpointCommand
+    from plugins.endpoints.api.routes import _reap_stale_commands, _naive_utcnow
+
+    now = _naive_utcnow()
+    asset_id = 4242
+
+    stale_running = EndpointCommand(
+        assetid=asset_id, action='mtconnect_start',
+        status=EndpointCommand.STATUS_RUNNING,
+        createdat=now - timedelta(hours=2),
+        claimedat=now - timedelta(hours=2))
+    stale_pending = EndpointCommand(
+        assetid=asset_id, action='mtconnect_stop',
+        status=EndpointCommand.STATUS_PENDING,
+        createdat=now - timedelta(hours=2))
+    fresh_running = EndpointCommand(
+        assetid=asset_id + 1, action='mtconnect_start',
+        status=EndpointCommand.STATUS_RUNNING,
+        createdat=now, claimedat=now)
+    db.session.add_all([stale_running, stale_pending, fresh_running])
+    db.session.commit()
+
+    reaped = _reap_stale_commands(asset_id)
+    db.session.commit()
+
+    reaped_ids = {command.endpointcommandid for command in reaped}
+    assert stale_running.endpointcommandid in reaped_ids
+    assert stale_pending.endpointcommandid in reaped_ids
+    assert stale_running.status == EndpointCommand.STATUS_EXPIRED
+    assert stale_pending.status == EndpointCommand.STATUS_EXPIRED
+    assert stale_running.completedat is not None
+    assert stale_running.resultmessage
+    # A live, recently claimed command on another endpoint is untouched.
+    assert fresh_running.status == EndpointCommand.STATUS_RUNNING
+
+
+def test_reap_leaves_a_recently_claimed_running_command_in_flight(db):
+    from plugins.endpoints.models import EndpointCommand
+    from plugins.endpoints.api.routes import _reap_stale_commands, _naive_utcnow
+
+    now = _naive_utcnow()
+    asset_id = 777
+
+    # Claimed a minute ago: a slow-but-alive command must not be reaped.
+    running = EndpointCommand(
+        assetid=asset_id, action='mtconnect_start',
+        status=EndpointCommand.STATUS_RUNNING,
+        createdat=now - timedelta(minutes=1),
+        claimedat=now - timedelta(minutes=1))
+    db.session.add(running)
+    db.session.commit()
+
+    reaped = _reap_stale_commands(asset_id)
+    db.session.commit()
+
+    assert reaped == []
+    assert running.status == EndpointCommand.STATUS_RUNNING

tests/test_no_hidden_tests.py

@@ -0,0 +1,50 @@
+"""No test file may sit where pytest will not collect it.
+
+pytest.ini sets `testpaths = tests`, so a test file anywhere else is never run
+by `pytest` and never run in CI. It still passes review, still gets maintained,
+and still reports nothing.
+
+That is not hypothetical. plugins/endpoints/tests/test_plugin.py arrived with a
+merge carrying 55 lines of delivery assertions and was collected ZERO times; run
+directly, five of its tests failed. plugins/printedparts/tests/test_plugin.py had
+been sitting uncollected for longer. Both are now under tests/.
+
+The failure mode is the worst kind: the suite is green, the coverage is imaginary,
+and the authorisation on a route can be deleted without anything going red.
+"""
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[1]
+
+# Where pytest actually looks (pytest.ini: testpaths = tests).
+COLLECTED = REPO / 'tests'
+
+# Trees that legitimately hold test-shaped files pytest must not collect:
+# vendored dependencies, build output, and the frontend's own vitest specs.
+IGNORED = ('node_modules', 'venv', '.git', 'dist', '__pycache__',
+           'site-packages', '.plugins-staged', 'frontend')
+
+# The Windows installer stages a whole copy of the app under here. It is build
+# output, not source, and the export excludes it - caught by this test on its
+# first run, which is the sort of thing the ignore list exists for.
+IGNORED_TREES = ('deploy/windows/installer/bundle',)
+
+
+def test_every_test_file_lives_where_pytest_looks():
+    stray = []
+    for path in REPO.rglob('test_*.py'):
+        if any(part in IGNORED for part in path.parts):
+            continue
+        relative = path.relative_to(REPO).as_posix()
+        if any(relative.startswith(tree) for tree in IGNORED_TREES):
+            continue
+        if COLLECTED in path.parents:
+            continue
+        stray.append(path.relative_to(REPO))
+
+    assert not stray, (
+        'These test files are never collected, because pytest.ini limits\n'
+        'collection to tests/. They pass review and report nothing:\n  '
+        + '\n  '.join(str(p) for p in sorted(stray))
+        + '\n\nMove them under tests/ (tests/test_plugins/ for plugin tests).'
+    )

tests/test_plugin_migrations.py

@@ -91,9 +91,10 @@ EXPECTED_HEAD_REVISION['notifications'] = 'notifications0005boardorder'
 EXPECTED_HEAD_REVISION['warranty'] = 'warranty0002proof'
 # endpoints is a NEW post-cutover plugin: its 0001 genuinely creates the
 # endpointstates + endpointevents tables the core chain never owned, 0002
-# adds the endpointcommands queue plus the MTConnect state columns, and 0003
-# adds the generic command target/targetkind columns.
-EXPECTED_HEAD_REVISION['endpoints'] = 'endpoints0003cmdtarget'
+# adds the endpointcommands queue plus the MTConnect state columns, 0003
+# adds the generic command target/targetkind columns, and 0004 adds the
+# endpointapplications SBOM snapshot table.
+EXPECTED_HEAD_REVISION['endpoints'] = 'endpoints0004apps'
 
 # Plugins built after the cutover: their 0001 baseline really creates tables the
 # core chain never owned.

tests/test_plugins/test_endpoint_applications_model.py

@@ -0,0 +1,87 @@
+"""The installed-software snapshot table: it must actually accept inserts.
+
+This table is rewritten wholesale on every endpoint check-in - delete the
+asset's rows, insert the current inventory - so its surrogate key climbs at
+(endpoints x installed apps) per report and never reuses a value. On MySQL a
+32-bit key exhausts and inserts stop working permanently.
+
+Widening it to BigInteger broke every insert on SQLite, because SQLite only
+autoincrements a column typed exactly INTEGER PRIMARY KEY. Neither fault was
+caught by the suite, for the same reason: nothing inserted into this table at
+all. This does.
+"""
+from shopdb.api import db
+from plugins.endpoints.models.endpoint import EndpointApplication
+
+
+def test_rows_insert_and_the_key_autoincrements(app):
+    with app.app_context():
+        db.create_all()
+        first = EndpointApplication(assetid=1, displayname='Probe', displayversion='1.0')
+        second = EndpointApplication(assetid=1, displayname='Probe 2', displayversion='2.0')
+        db.session.add_all([first, second])
+        db.session.commit()
+
+        assert first.endpointapplicationid is not None
+        assert second.endpointapplicationid is not None
+        assert second.endpointapplicationid != first.endpointapplicationid
+
+
+def test_the_key_is_wide_enough_for_a_table_that_is_rewritten_every_cycle(app):
+    """BIGINT on MySQL, INTEGER on SQLite - both halves matter.
+
+    Dropping the variant breaks SQLite inserts; dropping the BigInteger breaks
+    MySQL years later, which is worse because it is silent until it is not.
+    """
+    from sqlalchemy.dialects import mysql, sqlite
+
+    with app.app_context():
+        column = EndpointApplication.__table__.c.endpointapplicationid
+        assert 'BIGINT' in str(column.type.compile(dialect=mysql.dialect()))
+        assert 'INTEGER' in str(column.type.compile(dialect=sqlite.dialect()))
+
+
+def test_over_long_registry_values_are_clamped_not_fatal(app):
+    """One malformed Uninstall entry must not cost the whole check-in.
+
+    On MySQL in strict mode an over-long value raises Data too long and fails the
+    transaction, taking telemetry and events down with it - so that endpoint goes
+    silent until somebody uninstalls the offending program. SQLite does not
+    enforce declared lengths, so the suite would never have shown it.
+    """
+    from plugins.endpoints.plugin import EndpointsPlugin
+
+    with app.app_context():
+        db.create_all()
+        warnings = []
+        stored = EndpointsPlugin()._replace_applications(
+            assetid=4242,
+            applications=[{
+                'displayname': 'A' * 400,
+                'displayversion': 'V' * 400,
+                'publisher': 'P' * 400,
+            }],
+            warnings=warnings,
+        )
+        db.session.commit()
+
+        assert stored == 1
+        row = EndpointApplication.query.filter_by(assetid=4242).one()
+        assert len(row.displayname) == 255
+        assert len(row.displayversion) == 128
+        assert len(row.publisher) == 255
+
+
+def test_a_blank_value_becomes_null_rather_than_an_empty_string(app):
+    from plugins.endpoints.plugin import EndpointsPlugin
+
+    with app.app_context():
+        db.create_all()
+        EndpointsPlugin()._replace_applications(
+            assetid=4243,
+            applications=[{'displayname': 'Thing', 'publisher': '   '}],
+            warnings=[],
+        )
+        db.session.commit()
+        row = EndpointApplication.query.filter_by(assetid=4243).one()
+        assert row.publisher is None

tests/test_plugins/test_endpoint_delivery_descriptor.py

@@ -0,0 +1,81 @@
+"""An update_app delivery must pin the bytes it actually delivers.
+
+The agent verifies the downloaded file against the descriptor's sha256 and fails
+closed on a mismatch - which is worthless if the descriptor carries no digest,
+and misleading if it carries a digest for a different file.
+
+Both were true of the version: branch. It pinned AppVersion.sha256, but
+/api/endpoints/apppackage/<appversionid> resolves the version to its application
+and serves application.installpath, so the digest described an artifact that
+route never sends; where the version had no sha256 the descriptor carried none
+at all and the agent had nothing to check.
+
+It also ended the URL at the id, so an MSI arrived with no extension and the
+agent's Path.GetExtension could not route it through msiexec.
+"""
+import pytest
+
+from shopdb.api import db
+from shopdb.core.models import Application, AppVersion
+
+
+@pytest.fixture
+def hosted_app(app, request):
+    # Unique per test: appname is unique-constrained and the database outlives
+    # a single test here, so a fixed name collides on the second use.
+    with app.app_context():
+        db.create_all()
+        application = Application(
+            appname='Widget-%s' % request.node.name[-24:],
+            installpath='/api/applications/package/widget-setup.msi',
+            installersha256='a' * 64,
+        )
+        db.session.add(application)
+        db.session.commit()
+        version = AppVersion(appid=application.appid, version='2.1', sha256=None)
+        db.session.add(version)
+        db.session.commit()
+        yield application.appid, version.appversionid
+
+
+def test_a_version_delivery_carries_a_digest_even_when_the_version_has_none(app, hosted_app):
+    from plugins.endpoints.api.routes import _resolve_update_app
+
+    appid, appversionid = hosted_app
+    with app.app_context():
+        descriptor, error = _resolve_update_app(f'version:{appversionid}')
+
+    assert error is None, error
+    # Not None: this is the whole point. A blank pin makes the agent fail open.
+    assert descriptor['sha256'] == 'a' * 64
+
+
+def test_a_version_delivery_keeps_the_installer_extension(app, hosted_app):
+    """Without the filename an MSI is not routed through msiexec."""
+    from plugins.endpoints.api.routes import _resolve_update_app
+
+    appid, appversionid = hosted_app
+    with app.app_context():
+        descriptor, _ = _resolve_update_app(f'version:{appversionid}')
+
+    assert descriptor['installpath'].endswith('.msi')
+
+
+def test_a_package_with_no_recorded_digest_is_refused_not_delivered_unverified(app):
+    """Refusing to enqueue beats delivering something nothing can verify."""
+    from plugins.endpoints.api.routes import _resolve_update_app
+
+    with app.app_context():
+        db.create_all()
+        application = Application(appname='Unhashed-%s' % id(app),
+                                  installpath='/api/applications/package/x.exe')
+        db.session.add(application)
+        db.session.commit()
+        version = AppVersion(appid=application.appid, version='1.0', sha256=None)
+        db.session.add(version)
+        db.session.commit()
+
+        descriptor, error = _resolve_update_app(f'version:{version.appversionid}')
+
+    assert descriptor is None
+    assert 'SHA-256' in error

tests/test_plugins/test_endpoints_plugin.py

@@ -0,0 +1,251 @@
+"""Endpoints plugin smoke + collector-contract tests.
+
+Asserts the plugin loads cleanly, satisfies the framework contract, and that
+its ADR-006 collector schema is well formed. Extend with DB-backed ingest tests
+as the plugin grows.
+"""
+
+from flask import Blueprint
+
+from plugins.endpoints.plugin import EndpointsPlugin, CURATED_EVENT_IDS
+from plugins.endpoints.eventcatalog import EVENT_CATALOG, CRITICAL_EVENT_IDS
+from plugins.endpoints.commands import (
+    COMMAND_ALLOWLIST, is_allowed_action, elevated_permission_for,
+    requires_target,
+)
+
+
+def test_endpoints_plugin_meta_is_valid():
+    """meta returns a PluginMeta with the expected name and prefix."""
+    plugin = EndpointsPlugin()
+    assert plugin.meta.name == 'endpoints'
+    assert plugin.meta.api_prefix == '/api/endpoints'
+    assert 'computers' in plugin.meta.dependencies
+
+
+def test_endpoints_plugin_get_blueprint_returns_blueprint():
+    """get_blueprint returns a Flask Blueprint, not None."""
+    plugin = EndpointsPlugin()
+    assert isinstance(plugin.get_blueprint(), Blueprint)
+
+
+def test_endpoints_plugin_get_models_returns_models():
+    """get_models returns the two telemetry tables."""
+    plugin = EndpointsPlugin()
+    models = plugin.get_models()
+    assert len(models) >= 2
+    for model in models:
+        assert hasattr(model, '__tablename__')
+
+
+def test_endpoints_collector_schema_identity_is_hostname():
+    """ADR-006 schema declares hostname as the identity field."""
+    plugin = EndpointsPlugin()
+    schema = plugin.get_collector_schema()
+    assert schema is not None
+    assert schema['identityfield'] == 'hostname'
+    assert 'hostname' in schema['fields']['required']
+
+
+def test_endpoints_curated_event_ids_include_core_security_ids():
+    """The curated catalog covers the agreed logon/stability IDs."""
+    for eventid in (4624, 4625, 4634, 4672, 4697, 4698, 41, 4618, 55, 7011,
+                    10016, 1001):
+        assert eventid in CURATED_EVENT_IDS
+
+
+def test_curated_ids_match_the_event_catalog():
+    """Ingest filter and display catalog cannot drift apart."""
+    assert CURATED_EVENT_IDS == frozenset(EVENT_CATALOG)
+
+
+def test_critical_event_ids_are_a_subset_of_the_catalog():
+    """Dashboard stability card only queries known critical IDs."""
+    assert set(CRITICAL_EVENT_IDS)
+    assert set(CRITICAL_EVENT_IDS).issubset(set(EVENT_CATALOG))
+
+
+def test_endpoints_asset_panels_are_computer_scoped():
+    """Every asset panel targets computer assets only, with an endpoint."""
+    plugin = EndpointsPlugin()
+    panels = plugin.get_asset_panels()
+    assert len(panels) == 6
+    for panel in panels:
+        assert panel['assettypes'] == ['computer']
+        assert panel['endpoint'].startswith('/api/endpoints/asset/{assetid}')
+        assert panel['render'] in ('keyvalue', 'list', 'table')
+
+
+def test_services_and_processes_are_split_into_two_filtered_cards():
+    """The single services card is now two cards filtered by row kind, both
+    reading the same services snapshot so a future top-20 collector is just
+    another filtered panel over the same feed."""
+    plugin = EndpointsPlugin()
+    panels = {p['id']: p for p in plugin.get_asset_panels()}
+    services = panels['endpoints-tracked-services']
+    processes = panels['endpoints-tracked-processes']
+    assert services['title'] == 'Tracked Services'
+    assert processes['title'] == 'Tracked Processes'
+    assert services['filter'] == {'key': 'kind', 'equals': 'service'}
+    assert processes['filter'] == {'key': 'kind', 'equals': 'process'}
+    # Both slice one endpoint feed.
+    assert services['endpoint'] == processes['endpoint']
+    assert services['endpoint'].endswith('/services')
+    # Command wiring carries over to both cards.
+    assert services['permission'] == 'endpoints.command'
+    assert processes['permission'] == 'endpoints.command'
+
+
+def test_activity_card_starts_collapsed_and_sits_below_live_state():
+    """The activity feed is history, so it must not push live state down.
+
+    Renamed from the events card when events and commands merged into one feed.
+    It is no longer the LAST panel - installed software sits below it - so the
+    assertion is that it ranks below every live-state panel rather than being
+    the maximum, which would break again the next time a reference panel is
+    added underneath.
+    """
+    plugin = EndpointsPlugin()
+    panels = plugin.get_asset_panels()
+    activity = next(p for p in panels if p['id'] == 'endpoints-activity')
+    # NOT collapsed by default, unlike the events card it replaced. The feed
+    # surfaces critical events, and a card that hides the one thing worth seeing
+    # is the reason the health dot and the visible rows disagreed. Collapsible,
+    # so a reader can put it away.
+    assert activity.get('collapsible') is True
+    assert activity.get('collapsedDefault') is not True
+    live = [p['position'] for p in panels
+            if p['id'] in ('endpoints-status', 'endpoints-tracked-services',
+                           'endpoints-tracked-processes', 'endpoints-interfaces')]
+    assert activity['position'] > max(live)
+
+
+def test_endpoints_dashboard_widgets_declared():
+    """Quiet + stability exception cards are declared and hide when empty."""
+    plugin = EndpointsPlugin()
+    widgets = plugin.get_dashboard_widgets()
+    ids = {w['id'] for w in widgets}
+    assert {'endpoints-quiet', 'endpoints-stability'} <= ids
+    for widget in widgets:
+        assert widget['render'] == 'exceptions'
+        assert widget['empty'] == 'hide'
+        # The fleet-wide cards read the whole roster, so they are gated on
+        # endpoints.fleet, not the per-endpoint endpoints.view a guest may hold.
+        assert widget['permission'] == 'endpoints.fleet'
+
+
+def test_endpoints_navigation_item_points_at_fleet_view():
+    """The fleet list view is exposed as a single /endpoints nav item."""
+    plugin = EndpointsPlugin()
+    items = plugin.get_navigation_items()
+    routes = {item['route'] for item in items}
+    assert '/endpoints' in routes
+
+
+def test_system_restart_is_allowlisted_and_policy_selectable():
+    """Restart is a real allowlisted action, so the policy builder (which
+    reads COMMAND_ALLOWLIST) surfaces it as a selectable action."""
+    assert is_allowed_action('system_restart')
+    assert 'system_restart' in COMMAND_ALLOWLIST
+    assert COMMAND_ALLOWLIST['system_restart']['label'] == 'Restart computer'
+
+
+def test_system_restart_requires_the_elevated_restart_permission():
+    """Restart maps to endpoints.restart so the enqueue route can demand a
+    heavier grant than the routine endpoints.command toggle. Routine actions
+    carry no elevated requirement."""
+    assert elevated_permission_for('system_restart') == 'endpoints.restart'
+    assert elevated_permission_for('mtconnect_start') is None
+
+
+def test_endpoints_declares_the_restart_permission():
+    """The dedicated restart permission is declared for role-grid seeding."""
+    plugin = EndpointsPlugin()
+    permissions = {name for name, *_ in plugin.get_permissions()}
+    assert 'endpoints.restart' in permissions
+    assert 'endpoints.command' in permissions
+
+
+def test_collect_now_is_allowlisted_targetless_and_routine():
+    """collect_now forces an off-cadence telemetry report. It is allowlisted so
+    the enqueue route accepts it, carries no wire target (fixed action), and
+    needs no elevated grant beyond endpoints.command."""
+    assert is_allowed_action('collect_now')
+    assert 'collect_now' in COMMAND_ALLOWLIST
+    assert not requires_target('collect_now')
+    assert elevated_permission_for('collect_now') is None
+
+
+def test_run_script_and_update_app_are_allowlisted_delivery_actions():
+    """The two software-delivery actions are allowlisted with a targetkind so
+    the enqueue route accepts them and carries their subject on the wire:
+    run_script carries a script name, update_app carries an appversionid."""
+    for action in ('run_script', 'update_app'):
+        assert is_allowed_action(action)
+        assert action in COMMAND_ALLOWLIST
+        assert requires_target(action)
+    assert COMMAND_ALLOWLIST['run_script']['targetkind'] == 'script'
+    assert COMMAND_ALLOWLIST['update_app']['targetkind'] == 'app'
+
+
+def test_delivery_actions_require_the_elevated_deploy_permission():
+    """run_script and update_app both demand endpoints.deploy ON TOP OF
+    endpoints.command, so pushing software is a strictly heavier grant than a
+    routine service/process toggle."""
+    assert elevated_permission_for('run_script') == 'endpoints.deploy'
+    assert elevated_permission_for('update_app') == 'endpoints.deploy'
+
+
+def test_endpoints_declares_the_deploy_permission():
+    """The dedicated software-delivery permission is declared for role seeding."""
+    plugin = EndpointsPlugin()
+    permissions = {name for name, *_ in plugin.get_permissions()}
+    assert 'endpoints.deploy' in permissions
+
+
+def test_known_payload_keys_cover_persisted_and_relayed_fields():
+    """The ingest allow-set must list every key the handler consumes today, so
+    those keys are never mislogged as 'unpersisted'. Anything the agent sends
+    outside this set is logged for observability before columns exist."""
+    from plugins.endpoints.plugin import KNOWN_PAYLOAD_KEYS
+
+    persisted_or_relayed = {
+        'hostname', 'adopt', 'loggedinuser', 'serialnumber', 'pctype',
+        'machinenumber', 'vendorname', 'modelnumber', 'osname', 'ipaddress',
+        'agentversion', 'lastboottime', 'uptimeseconds', 'idleseconds',
+        'cpupercent', 'memorypercent', 'services', 'ports', 'interfaces',
+        'scheduledtasks', 'events',
+    }
+    assert persisted_or_relayed <= KNOWN_PAYLOAD_KEYS
+
+
+def test_new_hardware_telemetry_keys_are_logged_not_silently_known():
+    """Disk/bios/memory inventory is collected at the agent before the server
+    persists it. Those keys must be OUTSIDE the known set so ingest logs them
+    rather than dropping them silently."""
+    from plugins.endpoints.plugin import KNOWN_PAYLOAD_KEYS
+
+    for key in ('disks', 'bios', 'memory', 'processor', 'osinfo', 'domain'):
+        assert key not in KNOWN_PAYLOAD_KEYS
+
+    # 'applications' USED to be in this list. It is persisted now - that is what
+    # the installed-software work added - so it belongs in the known set, and
+    # asserting its absence would fail the moment the feature it tests works.
+    assert 'applications' in KNOWN_PAYLOAD_KEYS
+
+
+
+def test_telemetrymeta_route_is_registered_for_freshness_gating():
+    """The WebUI gates panel refreshes on lastreportedat advancing, so the
+    lightweight freshness probe must be exposed on the plugin blueprint."""
+    from flask import Flask
+
+    application = Flask(__name__)
+    # A url_prefix is REQUIRED here: the fleet list registers as route(''), which
+    # Flask rejects as a bare rule and accepts under a prefix. That is deliberate
+    # - CONTRIBUTING says API routes carry no trailing slash - so the test has to
+    # mount the blueprint the way the app does.
+    application.register_blueprint(EndpointsPlugin().get_blueprint(),
+                                   url_prefix='/api/endpoints')
+    rules = {rule.rule for rule in application.url_map.iter_rules()}
+    assert any(rule.endswith('/asset/<int:asset_id>/telemetrymeta') for rule in rules)

tests/test_plugins/test_printedparts_plugin.py

@@ -0,0 +1,30 @@
+"""Printedparts plugin smoke tests.
+
+Asserts the plugin loads cleanly and satisfies the framework contract.
+Replace and extend with domain tests as you build the plugin out.
+"""
+
+from plugins.printedparts.plugin import PrintedpartsPlugin
+
+
+def test_printedparts_plugin_meta_is_valid():
+    """PrintedpartsPlugin.meta returns a PluginMeta with the expected name."""
+    plugin = PrintedpartsPlugin()
+    assert plugin.meta.name == 'printedparts'
+    assert plugin.meta.api_prefix == '/api/printedparts'
+
+
+def test_printedparts_plugin_get_blueprint_returns_blueprint():
+    """get_blueprint returns a Flask Blueprint, not None."""
+    from flask import Blueprint
+    plugin = PrintedpartsPlugin()
+    assert isinstance(plugin.get_blueprint(), Blueprint)
+
+
+def test_printedparts_plugin_get_models_returns_a_model():
+    """get_models returns a list with at least one SQLAlchemy model."""
+    plugin = PrintedpartsPlugin()
+    models = plugin.get_models()
+    assert len(models) >= 1
+    for model in models:
+        assert hasattr(model, '__tablename__')

tests/test_runtime_dependencies.py

@@ -38,6 +38,13 @@ ALLOWED_UNDECLARED = {
     'pip',
     'setuptools',
     'pkg_resources',
+    # python-docx, used ONLY by scripts/docs/generate_docx.py to turn local
+    # authored Markdown into DOCX deliverables in exports/. That script is a
+    # developer convenience: the app never imports it, no deployed site runs it,
+    # and the Markdown it reads is itself gitignored. Declaring it in the
+    # production requirements would ship a doc-generation library to every
+    # customer venv for no runtime purpose.
+    'docx',
 }