Extract employee directory into a plugin

Third core feature pulled into a plugin (blueprint-only, like slides). The
employee directory is a read-only lookup over a separate HR database.

- plugins/employees/: manifest (api_prefix /api/employees, no deps), api/ (moved
  blueprint, contract-pure: success/error/ErrorCodes + employee_connection all
  from shopdb.api), plugin.py (get_blueprint, get_models -> []).
- employee_connection STAYS core infrastructure in shopdb.api (config-driven
  external DB connector, shared by search + the notifications shopfloor feed). So
  no get_services needed and no contract change - the plugin owns the directory
  FEATURE, core owns the shared connector.
- Fixed a latent bug in the move: error paths used ErrorCodes.DATABASE_ERROR
  which does not exist -> ErrorCodes.INTERNAL_ERROR (so a directory outage now
  returns a clean 500 envelope instead of an AttributeError crash).
- De-cored: deleted shopdb/core/api/employees.py, removed from
  CORE_BLUEPRINT_NAMES + core/api/__init__ import/__all__. Registered in
  instance/plugins.json.

Pinned first: validation (400) + graceful-degrade (500) characterization tests;
the degrade test caught the DATABASE_ERROR bug and goes green with the fix.
184 tests pass, naming green, app boots 9 bundled plugins, endpoint verified live.

Plugin extractions complete: knowledgebase, slides, employees.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

plugins/employees/__init__.py

@@ -0,0 +1,5 @@
+"""Employees plugin package."""
+
+from .plugin import EmployeesPlugin
+
+__all__ = ['EmployeesPlugin']

plugins/employees/api/__init__.py

@@ -0,0 +1,5 @@
+"""Employees plugin API."""
+
+from .routes import employees_bp
+
+__all__ = ['employees_bp']

plugins/employees/api/routes.py

@@ -0,0 +1,150 @@
+"""Employee lookup API endpoints.
+
+These read from the separate employee directory DB (employee_connection is core
+infrastructure exposed via shopdb.api, shared with search + notifications). The
+endpoints are intentionally reachable by the unauthenticated shopfloor kiosk
+displays (recognition wall), so they are not JWT-gated; keep them read-only and
+never return more than the directory fields below.
+"""
+
+import logging
+
+from flask import Blueprint, request
+
+from shopdb.api import (
+    success_response,
+    error_response,
+    ErrorCodes,
+    employee_connection,
+)
+
+logger = logging.getLogger(__name__)
+
+employees_bp = Blueprint('employees', __name__)
+
+# Columns safe to expose to the directory/recognition UI
+_FIELDS = 'SSO, First_Name, Last_Name, Team, Role, Picture'
+
+
+@employees_bp.route('/search', methods=['GET'])
+def search_employees():
+    """
+    Search employees by name.
+
+    Query parameters:
+    - q: Search query (searches first and last name)
+    - limit: Max results (default 10)
+    """
+    query = request.args.get('q', '').strip()
+    limit = min(int(request.args.get('limit', 10)), 50)
+
+    if len(query) < 2:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'Search query must be at least 2 characters'
+        )
+
+    try:
+        conn = employee_connection()
+        with conn.cursor() as cur:
+            cur.execute(f'''
+                SELECT {_FIELDS}
+                FROM employees
+                WHERE First_Name LIKE %s
+                   OR Last_Name LIKE %s
+                   OR CAST(SSO AS CHAR) LIKE %s
+                ORDER BY Last_Name, First_Name
+                LIMIT %s
+            ''', (f'%{query}%', f'%{query}%', f'%{query}%', limit))
+            employees = cur.fetchall()
+        conn.close()
+        return success_response(employees)
+    except Exception:
+        logger.exception('Employee search failed')
+        return error_response(
+            ErrorCodes.INTERNAL_ERROR,
+            'Employee lookup failed',
+            http_code=500
+        )
+
+
+@employees_bp.route('/lookup/<sso>', methods=['GET'])
+def lookup_employee(sso):
+    """Look up a single employee by SSO."""
+    if not sso.isdigit():
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'SSO must be numeric'
+        )
+
+    try:
+        conn = employee_connection()
+        with conn.cursor() as cur:
+            cur.execute(
+                f'SELECT {_FIELDS} FROM employees WHERE SSO = %s',
+                (int(sso),)
+            )
+            employee = cur.fetchone()
+        conn.close()
+
+        if not employee:
+            return error_response(
+                ErrorCodes.NOT_FOUND,
+                f'Employee with SSO {sso} not found',
+                http_code=404
+            )
+
+        return success_response(employee)
+    except Exception:
+        logger.exception('Employee lookup failed for SSO %s', sso)
+        return error_response(
+            ErrorCodes.INTERNAL_ERROR,
+            'Employee lookup failed',
+            http_code=500
+        )
+
+
+@employees_bp.route('/lookup', methods=['GET'])
+def lookup_employees():
+    """
+    Look up multiple employees by SSO list.
+
+    Query parameters:
+    - sso: Comma-separated list of SSOs
+    """
+    sso_list = request.args.get('sso', '')
+    ssos = [s.strip() for s in sso_list.split(',') if s.strip().isdigit()]
+
+    if not ssos:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'At least one valid SSO is required'
+        )
+
+    try:
+        conn = employee_connection()
+        with conn.cursor() as cur:
+            placeholders = ','.join(['%s'] * len(ssos))
+            cur.execute(
+                f'SELECT {_FIELDS} FROM employees WHERE SSO IN ({placeholders})',
+                [int(s) for s in ssos]
+            )
+            employees = cur.fetchall()
+        conn.close()
+
+        names = ', '.join(
+            f"{e['First_Name'].strip()} {e['Last_Name'].strip()}"
+            for e in employees
+        )
+
+        return success_response({
+            'employees': employees,
+            'names': names
+        })
+    except Exception:
+        logger.exception('Employee multi-lookup failed')
+        return error_response(
+            ErrorCodes.INTERNAL_ERROR,
+            'Employee lookup failed',
+            http_code=500
+        )

plugins/employees/manifest.json

@@ -0,0 +1,12 @@
+{
+  "name": "employees",
+  "version": "1.0.0",
+  "description": "Read-only employee directory lookup (separate HR database)",
+  "author": "ShopDB Team",
+  "dependencies": [],
+  "core_version": ">=0.1.0,<1.0.0",
+  "api_prefix": "/api/employees",
+  "provides": {
+    "features": ["employee_directory"]
+  }
+}

plugins/employees/plugin.py

@@ -0,0 +1,63 @@
+"""Employees plugin main class.
+
+Blueprint-only plugin: a read-only employee directory lookup over a separate HR
+database. No model (the directory is an external DB) and no AssetType. The
+connection helper (employee_connection) stays core infrastructure in shopdb.api,
+shared with search and the notifications shopfloor feed.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import List, Dict, Optional, Type
+
+from flask import Flask, Blueprint
+
+from shopdb.plugins.base import BasePlugin, PluginMeta
+
+from .api import employees_bp
+
+logger = logging.getLogger(__name__)
+
+
+class EmployeesPlugin(BasePlugin):
+    """Employees plugin - read-only HR directory lookup."""
+
+    def __init__(self):
+        self._manifest = self._load_manifest()
+
+    def _load_manifest(self) -> Dict:
+        """Load plugin manifest from JSON file."""
+        manifest_path = Path(__file__).parent / 'manifest.json'
+        if manifest_path.exists():
+            with open(manifest_path, 'r') as f:
+                return json.load(f)
+        return {}
+
+    @property
+    def meta(self) -> PluginMeta:
+        """Return plugin metadata."""
+        return PluginMeta(
+            name=self._manifest.get('name', 'employees'),
+            version=self._manifest.get('version', '1.0.0'),
+            description=self._manifest.get(
+                'description',
+                'Read-only employee directory lookup'
+            ),
+            author=self._manifest.get('author', 'ShopDB Team'),
+            dependencies=self._manifest.get('dependencies', []),
+            core_version=self._manifest.get('core_version', '>=0.1.0,<1.0.0'),
+            api_prefix=self._manifest.get('api_prefix', '/api/employees'),
+        )
+
+    def get_blueprint(self) -> Optional[Blueprint]:
+        """Return Flask Blueprint with API routes."""
+        return employees_bp
+
+    def get_models(self) -> List[Type]:
+        """No models - the directory is an external database."""
+        return []
+
+    def init_app(self, app: Flask, db_instance) -> None:
+        """Initialize plugin with Flask app."""
+        logger.info(f"Employees plugin initialized (v{self.meta.version})")