mint-sdk 1.0.0__py3-none-any.whl

mint_sdk/__init__.py

@@ -0,0 +1,354 @@
+"""
+MINT Plugin SDK
+
+SDK for building analysis plugins that integrate with the MINT platform.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+
+try:
+    from mint_sdk._version import __version__
+except ImportError:
+    __version__ = "0.0.0"
+
+_LAZY_EXPORTS = {
+    # API Client
+    "MINTClient": ("mint_sdk.client", "MINTClient"),
+    # Core plugin classes
+    "AnalysisPlugin": ("mint_sdk.plugin", "AnalysisPlugin"),
+    "PluginMetadata": ("mint_sdk.models", "PluginMetadata"),
+    "PluginCapabilities": ("mint_sdk.models", "PluginCapabilities"),
+    "PluginNavItem": ("mint_sdk.models", "PluginNavItem"),
+    "PluginType": ("mint_sdk.models", "PluginType"),
+    "PlatformContext": ("mint_sdk.context", "PlatformContext"),
+    # Lifecycle types
+    "HealthStatus": ("mint_sdk.plugin_lifecycle", "HealthStatus"),
+    "PluginHealth": ("mint_sdk.plugin_lifecycle", "PluginHealth"),
+    "LifecycleHookResult": ("mint_sdk.plugin_lifecycle", "LifecycleHookResult"),
+    # Exceptions
+    "PluginException": ("mint_sdk.exceptions", "PluginException"),
+    "ValidationException": ("mint_sdk.exceptions", "ValidationException"),
+    "PermissionException": ("mint_sdk.exceptions", "PermissionException"),
+    "ConfigurationException": ("mint_sdk.exceptions", "ConfigurationException"),
+    "RepositoryException": ("mint_sdk.exceptions", "RepositoryException"),
+    "NotFoundException": ("mint_sdk.exceptions", "NotFoundException"),
+    "ConflictException": ("mint_sdk.exceptions", "ConflictException"),
+    "PluginLifecycleException": ("mint_sdk.exceptions", "PluginLifecycleException"),
+    # Local database
+    "LocalDatabase": ("mint_sdk.local_database", "LocalDatabase"),
+    "LocalDatabaseConfig": ("mint_sdk.local_database", "LocalDatabaseConfig"),
+    # Jobs
+    "JobProgress": ("mint_sdk.jobs", "JobProgress"),
+    "JobId": ("mint_sdk.jobs", "JobId"),
+    "JobRegistry": ("mint_sdk.jobs", "JobRegistry"),
+    "JobState": ("mint_sdk.jobs", "JobState"),
+    "JobStatus": ("mint_sdk.jobs", "JobStatus"),
+    "TERMINAL_JOB_STATUSES": ("mint_sdk.jobs", "TERMINAL_JOB_STATUSES"),
+    # Data models
+    "Experiment": ("mint_sdk.repositories", "Experiment"),
+    "DesignData": ("mint_sdk.repositories", "DesignData"),
+    "PluginAnalysisResult": ("mint_sdk.repositories", "PluginAnalysisResult"),
+    "User": ("mint_sdk.repositories", "User"),
+    "UserPluginRole": ("mint_sdk.repositories", "UserPluginRole"),
+    # Repository protocols
+    "ExperimentRepository": ("mint_sdk.repositories", "ExperimentRepository"),
+    "PluginDataRepository": ("mint_sdk.repositories", "PluginDataRepository"),
+    "PluginRoleRepository": ("mint_sdk.repositories", "PluginRoleRepository"),
+    "UserRepository": ("mint_sdk.repositories", "UserRepository"),
+    "PlatformConfig": ("mint_sdk.repositories", "PlatformConfig"),
+    # Export utilities
+    "auto_json_to_tree": ("mint_sdk.export", "auto_json_to_tree"),
+    "auto_json_to_csv": ("mint_sdk.export", "auto_json_to_csv"),
+    "auto_json_to_summary": ("mint_sdk.export", "auto_json_to_summary"),
+    # Logging
+    "get_plugin_logger": ("mint_sdk.logging", "get_plugin_logger"),
+    # Schema conversion
+    "settings_model_to_form_fields": ("mint_sdk.schema", "settings_model_to_form_fields"),
+    "settings_model_to_settings_schema": ("mint_sdk.schema", "settings_model_to_settings_schema"),
+    # Permission helpers
+    "ADMIN_ROLE": ("mint_sdk.permissions", "ADMIN_ROLE"),
+    "ADMIN_PANEL_PERMISSIONS": ("mint_sdk.permissions", "ADMIN_PANEL_PERMISSIONS"),
+    "can_access_admin": ("mint_sdk.permissions", "can_access_admin"),
+    "can_access_plugin": ("mint_sdk.permissions", "can_access_plugin"),
+    "can_access_policy": ("mint_sdk.permissions", "can_access_policy"),
+    "get_access_audience": ("mint_sdk.permissions", "get_access_audience"),
+    "get_user_permissions": ("mint_sdk.permissions", "get_user_permissions"),
+    "has_all_permissions": ("mint_sdk.permissions", "has_all_permissions"),
+    "has_any_permission": ("mint_sdk.permissions", "has_any_permission"),
+    "is_admin_role": ("mint_sdk.permissions", "is_admin_role"),
+    "is_admin_user": ("mint_sdk.permissions", "is_admin_user"),
+    # Instrument monitoring models
+    "AlertLevel": ("mint_sdk.instrument", "AlertLevel"),
+    "InstrumentAlert": ("mint_sdk.instrument", "InstrumentAlert"),
+    "InstrumentAlertBody": ("mint_sdk.instrument", "InstrumentAlertBody"),
+    "InstrumentState": ("mint_sdk.instrument", "InstrumentState"),
+    "InstrumentStatus": ("mint_sdk.instrument", "InstrumentStatus"),
+    "SampleInfo": ("mint_sdk.instrument", "SampleInfo"),
+    "SequenceProgress": ("mint_sdk.instrument", "SequenceProgress"),
+    "build_sequence_progress": ("mint_sdk.instrument", "build_sequence_progress"),
+    # LCMS sequence helpers
+    "LcmsContainerType": ("mint_sdk.lcms", "LcmsContainerType"),
+    "LcmsMethodPathEntry": ("mint_sdk.lcms", "LcmsMethodPathEntry"),
+    "LcmsPlateCell": ("mint_sdk.lcms", "LcmsPlateCell"),
+    "LcmsPlateType": ("mint_sdk.lcms", "LcmsPlateType"),
+    "LcmsPolarity": ("mint_sdk.lcms", "LcmsPolarity"),
+    "LcmsSequenceItem": ("mint_sdk.lcms", "LcmsSequenceItem"),
+    "LcmsSequenceParams": ("mint_sdk.lcms", "LcmsSequenceParams"),
+    "combine_lcms_sequence_csvs": ("mint_sdk.lcms", "combine_lcms_sequence_csvs"),
+    "extract_lcms_common_prefix": ("mint_sdk.lcms", "extract_lcms_common_prefix"),
+    "extract_lcms_sample_name": ("mint_sdk.lcms", "extract_lcms_sample_name"),
+    "infer_lcms_plate_type_from_positions": ("mint_sdk.lcms", "infer_lcms_plate_type_from_positions"),
+    "insert_lcms_item_at_intervals": ("mint_sdk.lcms", "insert_lcms_item_at_intervals"),
+    "lcms_sequence_items_to_csv": ("mint_sdk.lcms", "lcms_sequence_items_to_csv"),
+    "lcms_well_id_from_position": ("mint_sdk.lcms", "lcms_well_id_from_position"),
+    "number_lcms_sequence_items": ("mint_sdk.lcms", "number_lcms_sequence_items"),
+    "parse_lcms_sequence_csv": ("mint_sdk.lcms", "parse_lcms_sequence_csv"),
+    "plate_cells_to_lcms_sequence_items": ("mint_sdk.lcms", "plate_cells_to_lcms_sequence_items"),
+    "reconstruct_lcms_plate_cells_from_sequence_items": (
+        "mint_sdk.lcms",
+        "reconstruct_lcms_plate_cells_from_sequence_items",
+    ),
+    "reorder_lcms_sequence_numbers": ("mint_sdk.lcms", "reorder_lcms_sequence_numbers"),
+    "resolve_lcms_method_path": ("mint_sdk.lcms", "resolve_lcms_method_path"),
+    # R bridge
+    "RAnalysisBridge": ("mint_sdk.r", "RAnalysisBridge"),
+    "RScriptSpec": ("mint_sdk.r", "RScriptSpec"),
+    "RBridgeError": ("mint_sdk.r", "RBridgeError"),
+    "RRunProvenance": ("mint_sdk.r", "RRunProvenance"),
+    # Bio data templates
+    "BioTemplateEnvelope": ("mint_sdk.templates", "BioTemplateEnvelope"),
+    "TEMPLATE_COLLECTION_KEY": ("mint_sdk.templates", "TEMPLATE_COLLECTION_KEY"),
+    "BioTemplateCatalogEntry": ("mint_sdk.templates", "BioTemplateCatalogEntry"),
+    "BioTemplatePackEntry": ("mint_sdk.templates", "BioTemplatePackEntry"),
+    "BioTemplatePresetEntry": ("mint_sdk.templates", "BioTemplatePresetEntry"),
+    "PlateMapTemplate": ("mint_sdk.templates", "PlateMapTemplate"),
+    "SampleSheetTemplate": ("mint_sdk.templates", "SampleSheetTemplate"),
+    "SamplePrepTemplate": ("mint_sdk.templates", "SamplePrepTemplate"),
+    "CalibrationCurveTemplate": ("mint_sdk.templates", "CalibrationCurveTemplate"),
+    "DoseResponseTemplate": ("mint_sdk.templates", "DoseResponseTemplate"),
+    "FlowCytometryPanelTemplate": ("mint_sdk.templates", "FlowCytometryPanelTemplate"),
+    "InstrumentRunTemplate": ("mint_sdk.templates", "InstrumentRunTemplate"),
+    "QpcrPlateTemplate": ("mint_sdk.templates", "QpcrPlateTemplate"),
+    "TimeCourseTemplate": ("mint_sdk.templates", "TimeCourseTemplate"),
+    "AssayMatrixTemplate": ("mint_sdk.templates", "AssayMatrixTemplate"),
+    "ReagentListTemplate": ("mint_sdk.templates", "ReagentListTemplate"),
+    "ProtocolStepsTemplate": ("mint_sdk.templates", "ProtocolStepsTemplate"),
+    "TemplateValidationError": ("mint_sdk.templates", "TemplateValidationError"),
+    "get_template_info": ("mint_sdk.templates", "get_template_info"),
+    "list_template_catalog": ("mint_sdk.templates", "list_template_catalog"),
+    "require_template_info": ("mint_sdk.templates", "require_template_info"),
+    "get_template_pack_info": ("mint_sdk.templates", "get_template_pack_info"),
+    "list_template_packs": ("mint_sdk.templates", "list_template_packs"),
+    "require_template_pack_info": ("mint_sdk.templates", "require_template_pack_info"),
+    "get_template_preset_info": ("mint_sdk.templates", "get_template_preset_info"),
+    "list_template_presets": ("mint_sdk.templates", "list_template_presets"),
+    "require_template_preset_info": ("mint_sdk.templates", "require_template_preset_info"),
+    "save_template_preset_collection": ("mint_sdk.templates", "save_template_preset_collection"),
+    "save_template": ("mint_sdk.templates", "save_template"),
+    "load_template": ("mint_sdk.templates", "load_template"),
+    "create_template_collection": ("mint_sdk.templates", "create_template_collection"),
+    "create_template_preset_collection": ("mint_sdk.templates", "create_template_preset_collection"),
+    "create_elisa_assay_collection": ("mint_sdk.templates", "create_elisa_assay_collection"),
+    "create_flow_cytometry_assay_collection": ("mint_sdk.templates", "create_flow_cytometry_assay_collection"),
+    "create_lcms_batch_collection": ("mint_sdk.templates", "create_lcms_batch_collection"),
+    "create_qpcr_expression_collection": ("mint_sdk.templates", "create_qpcr_expression_collection"),
+    "create_targeted_metabolomics_collection": (
+        "mint_sdk.templates",
+        "create_targeted_metabolomics_collection",
+    ),
+    "create_wellplate_screen_collection": ("mint_sdk.templates", "create_wellplate_screen_collection"),
+    "create_western_blot_assay_collection": ("mint_sdk.templates", "create_western_blot_assay_collection"),
+    "extract_template_collection": ("mint_sdk.templates", "extract_template_collection"),
+    "save_template_collection": ("mint_sdk.templates", "save_template_collection"),
+    "load_template_collection": ("mint_sdk.templates", "load_template_collection"),
+    # Migration framework
+    "MigrationOps": ("mint_sdk.migrations", "MigrationOps"),
+    "MigrationResult": ("mint_sdk.migrations", "MigrationResult"),
+    "MigrationRunner": ("mint_sdk.migrations", "MigrationRunner"),
+    "PluginMigration": ("mint_sdk.migrations", "PluginMigration"),
+    # App factory and helpers
+    "create_standalone_app": ("mint_sdk.app", "create_standalone_app"),
+    "SPAStaticFiles": ("mint_sdk.app", "SPAStaticFiles"),
+    "PluginDependency": ("mint_sdk.app", "PluginDependency"),
+    "require_context": ("mint_sdk.app", "require_context"),
+}
+
+__all__ = [
+    # API Client
+    "MINTClient",
+    # Core plugin classes
+    "AnalysisPlugin",
+    "PluginMetadata",
+    "PluginCapabilities",
+    "PluginNavItem",
+    "PluginType",
+    "PlatformContext",
+    # Lifecycle types
+    "HealthStatus",
+    "PluginHealth",
+    "LifecycleHookResult",
+    # Exceptions
+    "PluginException",
+    "ValidationException",
+    "PermissionException",
+    "ConfigurationException",
+    "RepositoryException",
+    "NotFoundException",
+    "ConflictException",
+    "PluginLifecycleException",
+    # Local database
+    "LocalDatabase",
+    "LocalDatabaseConfig",
+    # Jobs
+    "JobProgress",
+    "JobId",
+    "JobRegistry",
+    "JobState",
+    "JobStatus",
+    "TERMINAL_JOB_STATUSES",
+    # Data models
+    "Experiment",
+    "DesignData",
+    "PluginAnalysisResult",
+    "User",
+    "UserPluginRole",
+    # Repository protocols
+    "ExperimentRepository",
+    "PluginDataRepository",
+    "PluginRoleRepository",
+    "UserRepository",
+    "PlatformConfig",
+    # Export utilities
+    "auto_json_to_tree",
+    "auto_json_to_csv",
+    "auto_json_to_summary",
+    # Logging
+    "get_plugin_logger",
+    # Schema conversion
+    "settings_model_to_form_fields",
+    "settings_model_to_settings_schema",
+    # Permission helpers
+    "ADMIN_ROLE",
+    "ADMIN_PANEL_PERMISSIONS",
+    "can_access_admin",
+    "can_access_plugin",
+    "can_access_policy",
+    "get_access_audience",
+    "get_user_permissions",
+    "has_all_permissions",
+    "has_any_permission",
+    "is_admin_role",
+    "is_admin_user",
+    # Instrument monitoring models
+    "AlertLevel",
+    "InstrumentAlert",
+    "InstrumentAlertBody",
+    "InstrumentState",
+    "InstrumentStatus",
+    "SampleInfo",
+    "SequenceProgress",
+    "build_sequence_progress",
+    # LCMS sequence helpers
+    "LcmsContainerType",
+    "LcmsMethodPathEntry",
+    "LcmsPlateCell",
+    "LcmsPlateType",
+    "LcmsPolarity",
+    "LcmsSequenceItem",
+    "LcmsSequenceParams",
+    "combine_lcms_sequence_csvs",
+    "extract_lcms_common_prefix",
+    "extract_lcms_sample_name",
+    "infer_lcms_plate_type_from_positions",
+    "insert_lcms_item_at_intervals",
+    "lcms_sequence_items_to_csv",
+    "lcms_well_id_from_position",
+    "number_lcms_sequence_items",
+    "parse_lcms_sequence_csv",
+    "plate_cells_to_lcms_sequence_items",
+    "reconstruct_lcms_plate_cells_from_sequence_items",
+    "reorder_lcms_sequence_numbers",
+    "resolve_lcms_method_path",
+    # R bridge
+    "RAnalysisBridge",
+    "RScriptSpec",
+    "RBridgeError",
+    "RRunProvenance",
+    # Bio data templates
+    "BioTemplateEnvelope",
+    "TEMPLATE_COLLECTION_KEY",
+    "BioTemplateCatalogEntry",
+    "BioTemplatePackEntry",
+    "BioTemplatePresetEntry",
+    "PlateMapTemplate",
+    "SampleSheetTemplate",
+    "SamplePrepTemplate",
+    "CalibrationCurveTemplate",
+    "DoseResponseTemplate",
+    "FlowCytometryPanelTemplate",
+    "InstrumentRunTemplate",
+    "QpcrPlateTemplate",
+    "TimeCourseTemplate",
+    "AssayMatrixTemplate",
+    "ReagentListTemplate",
+    "ProtocolStepsTemplate",
+    "TemplateValidationError",
+    "get_template_info",
+    "list_template_catalog",
+    "require_template_info",
+    "get_template_pack_info",
+    "list_template_packs",
+    "require_template_pack_info",
+    "get_template_preset_info",
+    "list_template_presets",
+    "require_template_preset_info",
+    "save_template_preset_collection",
+    "save_template",
+    "load_template",
+    "create_template_collection",
+    "create_template_preset_collection",
+    "create_elisa_assay_collection",
+    "create_flow_cytometry_assay_collection",
+    "create_lcms_batch_collection",
+    "create_qpcr_expression_collection",
+    "create_targeted_metabolomics_collection",
+    "create_wellplate_screen_collection",
+    "create_western_blot_assay_collection",
+    "extract_template_collection",
+    "save_template_collection",
+    "load_template_collection",
+    # Migration framework
+    "MigrationOps",
+    "MigrationResult",
+    "MigrationRunner",
+    "PluginMigration",
+    # App factory and helpers
+    "create_standalone_app",
+    "SPAStaticFiles",
+    "PluginDependency",
+    "require_context",
+]
+
+
+def __getattr__(name: str):
+    """Load public SDK symbols on first access.
+
+    Keeping package-root exports lazy avoids importing optional-heavy modules
+    such as SQLAlchemy and httpx during lightweight submodule imports like the
+    CLI entry point.
+    """
+    try:
+        module_name, attr_name = _LAZY_EXPORTS[name]
+    except KeyError as exc:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+
+    module = import_module(module_name)
+    value = getattr(module, attr_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

mint_sdk/_discover.py

@@ -0,0 +1,313 @@
+"""Plugin discovery from pyproject.toml without importing the plugin.
+
+Parses entry points, module paths, and routes prefix by inspecting files
+statically — no plugin code is executed.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python < 3.11
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+@dataclass(slots=True)
+class DiscoveredPlugin:
+    """Statically discovered plugin metadata."""
+
+    entry_point_name: str  # "drp-analysis"
+    module_path: str  # "mint_plugin_drp.plugin"
+    class_name: str  # "DRPAnalysisPlugin"
+    factory_target: str  # "mint_plugin_drp.plugin:create_standalone_app"
+    routes_prefix: str  # "/drp" (from source) or "/drp-analysis" (fallback)
+    project_name: str  # "mint-plugin-drp"
+    project_version: str | None  # "0.2.0" or None if dynamic
+    project_description: str  # from [project].description
+    has_frontend: bool  # frontend/package.json exists
+    metadata_name: str = ""  # PluginMetadata.name, if statically readable
+    metadata_version: str = ""  # PluginMetadata.version, if statically readable
+    metadata_description: str = ""  # PluginMetadata.description, if statically readable
+    metadata_analysis_type: str = ""  # PluginMetadata.analysis_type
+    metadata_plugin_type: str = ""  # PluginMetadata.plugin_type
+    metadata_author: str = ""  # PluginMetadata.author
+    metadata_homepage: str = ""  # PluginMetadata.homepage
+    metadata_license: str = ""  # PluginMetadata.license
+    metadata_icon: str = ""  # PluginMetadata.icon
+    metadata_color: str = ""  # PluginMetadata.color
+    metadata_nav_items: list[dict[str, Any]] | None = None
+
+
+def _read_full_pyproject(project_dir: Path) -> dict:
+    """Read and return the full pyproject.toml as a dict."""
+    path = project_dir / "pyproject.toml"
+    if not path.exists():
+        print(f"Error: {path} not found.", file=sys.stderr)
+        sys.exit(1)
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def _parse_entry_point(data: dict) -> tuple[str, str, str] | None:
+    """Extract (name, module_path, class_name) from [project.entry-points."mint.plugins"].
+
+    Returns None if no mint.plugins entry point is found.
+    """
+    entry_points = (
+        data.get("project", {}).get("entry-points", {}).get("mint.plugins", {})
+    )
+    if not entry_points:
+        return None
+
+    # Take the first entry point
+    name, value = next(iter(entry_points.items()))
+    # value is "mint_plugin_drp.plugin:DRPAnalysisPlugin"
+    if ":" not in value:
+        return None
+    module_path, class_name = value.rsplit(":", 1)
+    return name, module_path, class_name
+
+
+def _module_source_candidates(module_path: str, project_dir: Path) -> list[Path]:
+    """Return possible source file paths for a plugin module path."""
+    parts = module_path.split(".")
+    return [
+        project_dir / "src" / Path(*parts).with_suffix(".py"),
+        project_dir / Path(*parts).with_suffix(".py"),
+    ]
+
+
+def _read_module_source(module_path: str, project_dir: Path) -> str | None:
+    """Read a plugin module source file without importing it."""
+    for source_path in _module_source_candidates(module_path, project_dir):
+        if not source_path.exists():
+            continue
+        try:
+            return source_path.read_text()
+        except OSError:
+            continue
+    return None
+
+
+def _parse_routes_prefix_from_source(module_path: str, project_dir: Path) -> str | None:
+    """Parse PLUGIN_ROUTES_PREFIX from the plugin source file without importing it.
+
+    Looks for patterns like:
+        PLUGIN_ROUTES_PREFIX = "/drp"
+        PLUGIN_ROUTES_PREFIX = '/drp'
+    """
+    content = _read_module_source(module_path, project_dir)
+    if content:
+        match = re.search(
+            r'PLUGIN_ROUTES_PREFIX\s*=\s*["\'](/[^"\']+)["\']', content
+        )
+        if match:
+            return match.group(1)
+
+    return None
+
+
+def _is_call_named(node: ast.Call, name: str) -> bool:
+    func = node.func
+    if isinstance(func, ast.Name):
+        return func.id == name
+    return isinstance(func, ast.Attribute) and func.attr == name
+
+
+def _literal_value(node: ast.AST, constants: Mapping[str, Any] | None = None) -> Any:
+    try:
+        return ast.literal_eval(node)
+    except (ValueError, SyntaxError):
+        if isinstance(node, ast.Attribute):
+            return node.attr.lower()
+        if isinstance(node, ast.Name) and constants and node.id in constants:
+            return constants[node.id]
+        return None
+
+
+def _keyword_literal(
+    node: ast.Call,
+    name: str,
+    constants: Mapping[str, Any] | None = None,
+) -> Any:
+    for keyword in node.keywords:
+        if keyword.arg != name:
+            continue
+        return _literal_value(keyword.value, constants)
+    return None
+
+
+def _metadata_string(
+    node: ast.Call,
+    name: str,
+    constants: Mapping[str, Any],
+) -> str:
+    value = _keyword_literal(node, name, constants)
+    return value if isinstance(value, str) else ""
+
+
+def _parse_nav_items(node: ast.Call, constants: Mapping[str, Any]) -> list[dict[str, Any]]:
+    nav_items: list[dict[str, Any]] = []
+    for keyword in node.keywords:
+        if keyword.arg != "nav_items":
+            continue
+        if not isinstance(keyword.value, (ast.List, ast.Tuple)):
+            return nav_items
+        for item in keyword.value.elts:
+            if not isinstance(item, ast.Call) or not _is_call_named(item, "PluginNavItem"):
+                continue
+            nav_item: dict[str, Any] = {}
+            for key in (
+                "path",
+                "label",
+                "id",
+                "icon",
+                "description",
+                "requires_auth",
+                "requires_admin",
+                "requires_feature",
+            ):
+                value = _keyword_literal(item, key, constants)
+                if value not in (None, "", False):
+                    nav_item[key] = value
+            if nav_item.get("path") and nav_item.get("label"):
+                nav_items.append(nav_item)
+    return nav_items
+
+
+def _module_constants(tree: ast.Module) -> dict[str, Any]:
+    constants: dict[str, Any] = {}
+    for node in tree.body:
+        if isinstance(node, ast.Assign):
+            value = _literal_value(node.value, constants)
+            if value in (None, "", False):
+                continue
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    constants[target.id] = value
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            value = _literal_value(node.value, constants) if node.value is not None else None
+            if value not in (None, "", False):
+                constants[node.target.id] = value
+    return constants
+
+
+def _parse_metadata_from_source(module_path: str, project_dir: Path) -> dict[str, Any]:
+    """Parse simple PluginMetadata literal fields without importing the plugin."""
+    content = _read_module_source(module_path, project_dir)
+    if not content:
+        return {}
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return {}
+    constants = _module_constants(tree)
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call) or not _is_call_named(node, "PluginMetadata"):
+            continue
+        metadata: dict[str, Any] = {}
+        for key in (
+            "name",
+            "version",
+            "description",
+            "analysis_type",
+            "author",
+            "homepage",
+            "license",
+            "icon",
+            "color",
+        ):
+            if value := _metadata_string(node, key, constants):
+                metadata[key] = value
+        if plugin_type := _metadata_string(node, "plugin_type", constants):
+            metadata["plugin_type"] = plugin_type
+        if nav_items := _parse_nav_items(node, constants):
+            metadata["nav_items"] = nav_items
+        return metadata
+
+    return {}
+
+
+def discover_plugin(project_dir: Path) -> DiscoveredPlugin:
+    """Discover plugin metadata from pyproject.toml and source files.
+
+    Raises SystemExit if the project directory lacks required configuration.
+    """
+    data = _read_full_pyproject(project_dir)
+
+    project = data.get("project")
+    if not project:
+        print("Error: pyproject.toml has no [project] table.", file=sys.stderr)
+        sys.exit(1)
+
+    entry_point = _parse_entry_point(data)
+    if not entry_point:
+        print(
+            "Error: No [project.entry-points.\"mint.plugins\"] found in pyproject.toml.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    ep_name, module_path, class_name = entry_point
+
+    # Routes prefix: parse from source, fallback to /{entry_point_name}
+    routes_prefix = _parse_routes_prefix_from_source(module_path, project_dir)
+    if routes_prefix is None:
+        routes_prefix = f"/{ep_name}"
+
+    # Factory target for uvicorn --factory
+    factory_target = f"{module_path}:create_standalone_app"
+
+    # Version: static or None if dynamic
+    version = project.get("version")
+
+    has_frontend = (project_dir / "frontend" / "package.json").exists()
+    metadata = _parse_metadata_from_source(module_path, project_dir)
+
+    return DiscoveredPlugin(
+        entry_point_name=ep_name,
+        module_path=module_path,
+        class_name=class_name,
+        factory_target=factory_target,
+        routes_prefix=routes_prefix,
+        project_name=project["name"],
+        project_version=version,
+        project_description=project.get("description", ""),
+        has_frontend=has_frontend,
+        metadata_name=metadata.get("name", ""),
+        metadata_version=metadata.get("version", ""),
+        metadata_description=metadata.get("description", ""),
+        metadata_analysis_type=metadata.get("analysis_type", ""),
+        metadata_plugin_type=metadata.get("plugin_type", ""),
+        metadata_author=metadata.get("author", ""),
+        metadata_homepage=metadata.get("homepage", ""),
+        metadata_license=metadata.get("license", ""),
+        metadata_icon=metadata.get("icon", ""),
+        metadata_color=metadata.get("color", ""),
+        metadata_nav_items=metadata.get("nav_items"),
+    )
+
+
+def get_sdk_dependency_spec(project_dir: Path) -> str | None:
+    """Extract the mint-sdk version specifier from pyproject.toml dependencies.
+
+    Returns e.g. ">=0.9.4" or None if mint-sdk is not in dependencies.
+    """
+    data = _read_full_pyproject(project_dir)
+    deps = data.get("project", {}).get("dependencies", [])
+    for dep in deps:
+        # Match "mint-sdk>=0.9.4", "mint-sdk>=0.9.4,<1.0", "mint-sdk"
+        match = re.match(r"mint[-_]sdk\s*(.*)", dep, re.IGNORECASE)
+        if match:
+            spec = match.group(1).strip()
+            return spec if spec else "*"
+    return None