Extract Knowledge Base into a plugin (reference non-asset plugin)

First feature extracted from core into a plugin per "plugin is the product",
mirroring the notifications plugin. KB is a NON-asset plugin: it contributes a
model + blueprint + nav item but registers no AssetType.

- plugins/knowledgebase/: manifest.json (api_prefix /api/knowledgebase, no deps),
  models/ (KnowledgeBase, contract-pure imports via shopdb.api), api/ (the
  blueprint, same routes/prefix so the frontend is unchanged), plugin.py
  (get_blueprint + get_models + get_navigation_items).
- De-cored: removed shopdb/core/models/knowledgebase.py + api/knowledgebase.py,
  their __init__ exports, and 'knowledgebase' from CORE_BLUEPRINT_NAMES; dropped
  the hardcoded KB nav item from dashboard.py (now via the plugin nav hook).
- search.py and reports.py lazy-import KnowledgeBase from the plugin and degrade
  gracefully (search skips via _require_enabled when disabled; kb-popularity
  report returns 503 if the plugin is absent).
- Registered in instance/plugins.json (enabled).

The knowledgebase table stays in the core Alembic chain (bundled-plugin schema
folded into core, ADR-004); the model just maps it. KB was never in the
shopdb.api contract surface, so no __contract_version__ bump.

Pinned with characterization tests first (test_knowledgebase.py); they pass
unchanged against the plugin blueprint. 163 tests pass, naming green, app boots
7 bundled plugins, KB endpoint/nav/search verified live.

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

plugins/knowledgebase/__init__.py

@@ -0,0 +1,5 @@
+"""Knowledge Base plugin package."""
+
+from .plugin import KnowledgeBasePlugin
+
+__all__ = ['KnowledgeBasePlugin']

plugins/knowledgebase/api/__init__.py

@@ -0,0 +1,5 @@
+"""Knowledge Base plugin API."""
+
+from .routes import knowledgebase_bp
+
+__all__ = ['knowledgebase_bp']

plugins/knowledgebase/api/routes.py

@@ -3,15 +3,18 @@
 from flask import Blueprint, request
 from flask_jwt_extended import jwt_required
 
-from shopdb.extensions import db
-from shopdb.core.models import KnowledgeBase, Application
-from shopdb.utils.responses import (
+from shopdb.api import (
+    db,
+    Application,
     success_response,
     error_response,
     paginated_response,
-    ErrorCodes
+    ErrorCodes,
+    get_pagination_params,
+    paginate_query,
 )
-from shopdb.utils.pagination import get_pagination_params, paginate_query
+
+from ..models import KnowledgeBase
 
 knowledgebase_bp = Blueprint('knowledgebase', __name__)
 

plugins/knowledgebase/manifest.json

@@ -0,0 +1,12 @@
+{
+  "name": "knowledgebase",
+  "version": "1.0.0",
+  "description": "Knowledge Base articles linking to external resources",
+  "author": "ShopDB Team",
+  "dependencies": [],
+  "core_version": ">=0.1.0,<1.0.0",
+  "api_prefix": "/api/knowledgebase",
+  "provides": {
+    "features": ["knowledgebase"]
+  }
+}

plugins/knowledgebase/models/__init__.py

@@ -0,0 +1,5 @@
+"""Knowledge Base plugin models."""
+
+from .knowledgebase import KnowledgeBase
+
+__all__ = ['KnowledgeBase']

plugins/knowledgebase/models/knowledgebase.py

@@ -1,7 +1,13 @@
-"""Knowledge Base models."""
+"""Knowledge Base model.
 
-from shopdb.extensions import db
-from .base import BaseModel
+Non-asset plugin model. The `knowledgebase` table lives in the core Alembic
+chain (bundled-plugin schema is folded into core, ADR-004); this class just
+maps it and is registered via the plugin's get_models hook. The appid FK
+references the core applications table by name, which resolves at mapper config
+time without importing the core model.
+"""
+
+from shopdb.api import db, BaseModel
 
 
 class KnowledgeBase(BaseModel):
@@ -16,7 +22,7 @@ class KnowledgeBase(BaseModel):
     clicks = db.Column(db.Integer, default=0)
     lastupdated = db.Column(db.DateTime, default=db.func.now(), onupdate=db.func.now())
 
-    # Relationships
+    # Relationship to the core Application model (resolved by class name).
     application = db.relationship('Application', backref=db.backref('knowledgebase_articles', lazy='dynamic'))
 
     def __repr__(self):

plugins/knowledgebase/plugin.py

@@ -0,0 +1,74 @@
+"""Knowledge Base plugin main class.
+
+Reference NON-asset plugin: contributes a model + blueprint + nav item but no
+AssetType (it is not an asset). Mirrors the notifications plugin.
+"""
+
+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 .models import KnowledgeBase
+from .api import knowledgebase_bp
+
+logger = logging.getLogger(__name__)
+
+
+class KnowledgeBasePlugin(BasePlugin):
+    """Knowledge Base plugin - articles linking to external resources."""
+
+    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', 'knowledgebase'),
+            version=self._manifest.get('version', '1.0.0'),
+            description=self._manifest.get(
+                'description',
+                'Knowledge Base articles linking to external resources'
+            ),
+            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/knowledgebase'),
+        )
+
+    def get_blueprint(self) -> Optional[Blueprint]:
+        """Return Flask Blueprint with API routes."""
+        return knowledgebase_bp
+
+    def get_models(self) -> List[Type]:
+        """Return list of SQLAlchemy model classes."""
+        return [KnowledgeBase]
+
+    def init_app(self, app: Flask, db_instance) -> None:
+        """Initialize plugin with Flask app."""
+        logger.info(f"Knowledge Base plugin initialized (v{self.meta.version})")
+
+    def get_navigation_items(self) -> List[Dict]:
+        """Return navigation menu items."""
+        return [
+            {
+                'name': 'Knowledge Base',
+                'icon': 'book-open',
+                'route': '/knowledgebase',
+                'position': 35,
+                'section': 'information',
+            },
+        ]

shopdb/__init__.py

@@ -102,7 +102,6 @@ CORE_BLUEPRINT_NAMES = (
     'operatingsystems',
     'dashboard',
     'applications',
-    'knowledgebase',
     'search',
     'reports',
     'collector',

shopdb/core/api/__init__.py

@@ -11,7 +11,6 @@ from .locations import locations_bp
 from .operatingsystems import operatingsystems_bp
 from .dashboard import dashboard_bp
 from .applications import applications_bp
-from .knowledgebase import knowledgebase_bp
 from .search import search_bp
 from .reports import reports_bp
 from .collector import collector_bp
@@ -33,7 +32,6 @@ __all__ = [
     'operatingsystems_bp',
     'dashboard_bp',
     'applications_bp',
-    'knowledgebase_bp',
     'search_bp',
     'reports_bp',
     'collector_bp',

shopdb/core/api/dashboard.py

@@ -142,7 +142,6 @@ def get_navigation():
     # Add core information section items
     all_items.extend([
         {'name': 'Applications', 'icon': 'app-window', 'route': '/applications', 'position': 30, 'section': 'information'},
-        {'name': 'Knowledge Base', 'icon': 'book-open', 'route': '/knowledgebase', 'position': 35, 'section': 'information'},
         {'name': 'Reports', 'icon': 'bar-chart-3', 'route': '/reports', 'position': 40, 'section': 'information'},
     ])
 

shopdb/core/api/reports.py

@@ -9,7 +9,7 @@ from flask_jwt_extended import jwt_required
 from shopdb.extensions import db
 from shopdb.core.models import (
     Asset, AssetType, AssetStatus,
-    Application, KnowledgeBase
+    Application
 )
 from shopdb.utils.responses import success_response, error_response, ErrorCodes
 
@@ -165,6 +165,15 @@ def kb_popularity():
     """
     limit = min(int(request.args.get('limit', 20)), 100)
 
+    # Knowledge Base is a plugin; degrade gracefully if it is not installed.
+    try:
+        from plugins.knowledgebase.models import KnowledgeBase
+    except ImportError:
+        return error_response(
+            ErrorCodes.INTERNAL_ERROR,
+            'KB popularity requires the knowledgebase plugin',
+            http_code=503)
+
     articles = KnowledgeBase.query.filter(
         KnowledgeBase.isactive == True
     ).order_by(

shopdb/core/api/search.py

@@ -11,7 +11,7 @@ from sqlalchemy.orm import joinedload
 
 from shopdb.extensions import db
 from shopdb.core.models import (
-    Application, KnowledgeBase,
+    Application,
     Asset, AssetType, Communication, Vendor, Model
 )
 from shopdb.utils.responses import success_response
@@ -131,6 +131,8 @@ def _search_knowledgebase(query, search_term):
     """Search Knowledge Base by description and keywords."""
     results = []
     try:
+        _require_enabled('knowledgebase')
+        from plugins.knowledgebase.models import KnowledgeBase
         kb_articles = KnowledgeBase.query.filter(
             KnowledgeBase.isactive == True,
             db.or_(
@@ -153,6 +155,8 @@ def _search_knowledgebase(query, search_term):
                 'linkurl': kb.linkurl,
                 'relevance': relevance
             })
+    except ImportError:
+        pass  # knowledgebase plugin absent or disabled
     except Exception as e:
         logger.error(f"KnowledgeBase search failed: {e}")
     return results

shopdb/core/models/__init__.py

@@ -12,7 +12,6 @@ from .relationship import AssetRelationship, RelationshipType
 from .communication import Communication, CommunicationType
 from .user import User, Role, Permission
 from .application import Application, AppVersion, AppOwner, SupportTeam
-from .knowledgebase import KnowledgeBase
 from .setting import Setting
 from .auditlog import AuditLog
 
@@ -50,7 +49,6 @@ __all__ = [
     'AppOwner',
     'SupportTeam',
     # Knowledge Base
-    'KnowledgeBase',
     # Settings
     'Setting',
     # Audit

tests/test_core/test_knowledgebase.py

@@ -0,0 +1,34 @@
+"""Characterization tests for the Knowledge Base API.
+
+Written before extracting Knowledge Base into a plugin (pinning-flask-behavior):
+the endpoints must behave identically whether KB is a core blueprint or a plugin
+blueprint, since both register at /api/knowledgebase.
+"""
+
+
+def test_create_list_get_article(client, db, auth_headers):
+    """Create an article, see it in the list, fetch it by id."""
+    created = client.post('/api/knowledgebase',
+                          json={'shortdescription': 'How to reset a printer',
+                                'linkurl': 'https://kb.example/printer-reset',
+                                'keywords': 'printer reset'},
+                          headers=auth_headers)
+    assert created.status_code == 201, created.get_json()
+    linkid = created.get_json()['data']['linkid']
+
+    listing = client.get('/api/knowledgebase', headers=auth_headers)
+    assert listing.status_code == 200
+    ids = [a['linkid'] for a in listing.get_json()['data']]
+    assert linkid in ids
+
+    fetched = client.get(f'/api/knowledgebase/{linkid}', headers=auth_headers)
+    assert fetched.status_code == 200
+    assert fetched.get_json()['data']['shortdescription'] == 'How to reset a printer'
+
+
+def test_create_requires_shortdescription(client, db, auth_headers):
+    """shortdescription is required."""
+    resp = client.post('/api/knowledgebase',
+                       json={'linkurl': 'https://kb.example/x'},
+                       headers=auth_headers)
+    assert resp.status_code == 400

tests/test_plugin_contract.py

@@ -17,7 +17,7 @@ from shopdb.plugins import plugin_manager
 from shopdb.plugins.base import BasePlugin, PluginMeta
 
 
-BUNDLED_PLUGINS = ('computers', 'equipment', 'network', 'notifications', 'printers', 'usb')
+BUNDLED_PLUGINS = ('computers', 'equipment', 'knowledgebase', 'network', 'notifications', 'printers', 'usb')
 
 
 @pytest.fixture

tests/test_smoke.py

@@ -89,12 +89,13 @@ def test_paginated_response_shape(client, auth_headers):
 
 
 def test_plugin_loader_discovers_bundled_plugins(app):
-    """Plugin manager finds the six bundled plugins."""
+    """Plugin manager finds the bundled plugins."""
     from shopdb.plugins import plugin_manager
 
     expected_plugins = {
         'computers',
         'equipment',
+        'knowledgebase',
         'network',
         'notifications',
         'printers',