leocrm/docs/plugin-checklist.md

Plugin Checklist — MUST-PASS before merge

Every new or changed plugin must pass this checklist. Each item maps to a failure class that actually occurred in this codebase (see PROGRESS.md architecture-repair section). CI runs the automated checks; reviewers verify the rest.

Automated checks (CI)

• python scripts/check_cross_plugin_imports.py → 0 violations (no direct imports from other plugins — use get_contract())
• python scripts/check_migration_hashes.py → OK (migrations ≤0092 unchanged)
• npx tsc --noEmit clean (if frontend contributions changed)
• pytest smoke of affected suites passes

Architecture rules

1. No cross-plugin imports — access other plugins only via from app.plugins.builtins.contracts import get_contract. If a contract is missing, define it in the owning plugin's contracts.py. Failure class: silent dead code when the imported symbol moved.

2. Lifecycle symmetry — everything registered in on_activate (contracts, services, event handlers, hooks, tools, providers) must be deregistered in on_deactivate, in the correct order: own cleanup FIRST, then super().on_deactivate(). Failure class: stale services after deactivation; ImportError at every deactivate because a helper was imported as module function.

3. Every route has a permission — no auth-only routes. Every FrontendMenuItem and FrontendPageRoute carries its permission field. Failure class: dead guards checking permissions that don't exist.

4. Declare dependencies — if your plugin uses another plugin's data or contracts, declare it in manifest.dependencies. Activation order is topological; your plugin cannot be deactivated while dependents are active.

5. Entities via registration — return models from get_entity_models(); never assume core tables. The /entity-permissions/registry endpoint is generated dynamically from these registrations.

6. Frontend components via manifest — pages, menu items, settings pages, detail tabs, dashboard widgets come from the manifest. Register new page components in frontend/src/components/plugins/PluginLoader.tsx STATIC_COMPONENT_MAP so production builds can chunk them. Failure class: ghost components — manifest references a component that does not exist; tab shows error boundary in production.

7. Migrations follow convention — Alembic revisions touching plugin-owned tables must be conditional (to_regclass guard) with an idempotent plugin-side SQL migration for dual-path convergence. Failure class: fresh-install breaks because Alembic ran before plugins.

8. Audit log on every mutation — use log_audit from app.core.audit.

9. datetime only with UTC — datetime.now(UTC), never utcnow().

10. Pydantic schemas validate input — no raw dict bodies on routes.

11. Agent tools carry permissions — any tool registered in the tool registry declares the permission of the underlying endpoint.

12. Tests against real PostgreSQL — ephemeral DB per run (see app/plugins/builtins/automation/tests/test_automation.py fixture); create real tenant/user rows instead of random UUIDs for FK columns.

Review checklist (human/agent reviewer)

• Checklist items above verified, not assumed
• New mechanisms documented in docs/plugin-development-guide.md
• PROGRESS.md updated with finding ID + commit hash + verification proof