task-d.7.9

docs/implementation/task-d79-installation-profiles-setup-plugin-registry.md

@@ -0,0 +1,80 @@
+# Task D.7.9 Installation Profiles & Setup Plugin Registry
+
+Date: 2026-07-03
+Status: implemented
+
+## Scope Delivered
+
+Added setup plugin platform layer:
+
+- `src/features/setup/plugins/plugin-types.ts`
+- `src/features/setup/plugins/plugin-registry.ts`
+- `src/features/setup/plugins/installation-profile.ts`
+- `src/features/setup/plugins/foundation/foundation-plugin.ts`
+- `src/features/setup/plugins/crm/crm-setup-plugin.ts`
+- `src/features/setup/plugins/crm/crm-installation-profile.ts`
+
+Added installation profile API:
+
+- `GET /api/setup/profiles`
+
+Updated existing setup APIs:
+
+- `GET /api/setup/templates?profile=<profileId>` now returns plugin-aware metadata while preserving legacy template fields.
+- `GET /api/setup/readiness?profile=<profileId>` includes plugin registry readiness checks.
+- `POST /api/setup/verify` accepts optional `profileId` and includes plugin registry verification checks.
+
+Updated Setup Wizard:
+
+- Loads installation profiles from the setup plugin registry.
+- Allows profile selection.
+- Builds wizard stepper from profile-resolved wizard steps with fallback to existing steps.
+- Displays installed setup modules/plugins.
+
+Added plugin documentation:
+
+- `docs/setup/installation-profiles.md`
+- `docs/setup/setup-plugin-development.md`
+
+Added setup tests:
+
+- `src/tests/setup/setup-plugin-registry.test.ts`
+
+## Profiles
+
+Implemented profiles:
+
+- `crm_starter`
+- `crm_demo`
+- `production`
+- `restore_backup`
+- `custom`
+
+## Plugins
+
+Implemented built-in plugins:
+
+- `foundation`
+  - owns setup platform foundations, setup state, seed manifests, reset framework, CSV framework, and foundation golden dataset registration
+- `crm`
+  - owns CRM templates, CRM verification registration, CRM reset scopes, CRM reseed target registration, and CRM golden dataset registration
+
+## Compatibility Notes
+
+- No breaking API field removals were introduced.
+- Existing template metadata fields remain: `file`, `seedType`, `importOrder`, `supported`, `requiredColumns`, `description`.
+- New template metadata fields are additive: `plugin`, `profiles`, `visible`.
+- Existing CSV preview/commit behavior is unchanged.
+- Existing reset/reseed behavior is unchanged.
+- External plugin loading, marketplace behavior, and new business modules remain out of scope.
+
+## Validation
+
+- `npm run typecheck -- --pretty false` passed.
+- `npm run test:setup` passed: 20 tests.
+- `npx oxlint src/features/setup/plugins src/app/api/setup/profiles src/app/api/setup/templates src/app/api/setup/readiness src/app/api/setup/verify src/features/setup/components/setup-wizard.tsx src/features/setup/api src/tests/setup` passed.
+
+## Residual Notes
+
+- Readiness and verification services now aggregate plugin registry checks additively. Existing concrete CRM checks remain in place to avoid regression.
+- Future module plugins should register through `plugin-registry.ts` rather than editing the setup wizard directly.

docs/setup/installation-profiles.md

@@ -0,0 +1,20 @@
+# Installation Profiles
+
+Installation profiles select setup plugins, wizard steps, required templates, verification checks, reset scopes, and reseed targets.
+
+Current profiles:
+
+- `crm_starter`: foundation plus CRM structure.
+- `crm_demo`: foundation plus CRM golden/demo dataset.
+- `production`: foundation plus CRM production setup, with destructive maintenance disabled by default.
+- `restore_backup`: minimal readiness and verification for restored environments.
+- `custom`: operator-selected setup modules and templates.
+
+Profiles are resolved by `src/features/setup/plugins/plugin-registry.ts` and exposed by:
+
+- `GET /api/setup/profiles`
+- `GET /api/setup/templates?profile=<profileId>`
+- `GET /api/setup/readiness?profile=<profileId>`
+- `POST /api/setup/verify` with optional `profileId`
+
+The setup wizard uses the selected profile to render profile-aware plugin metadata and wizard steps.

docs/setup/setup-plugin-development.md

@@ -0,0 +1,37 @@
+# Setup Plugin Development
+
+Setup plugins let modules extend setup without editing the setup wizard directly.
+
+Plugin source lives under:
+
+```text
+src/features/setup/plugins/
+```
+
+Required plugin contract:
+
+- plugin id and version
+- installation profiles
+- setup templates
+- wizard steps
+- readiness checks
+- verification checks
+- CSV preview validators
+- import handlers
+- reset scopes
+- reseed targets
+- golden dataset registration
+
+Core plugins:
+
+- `foundation`: setup platform foundations, state, seed manifests, reset framework, CSV framework
+- `crm`: CRM templates, CRM verification, CRM reset scopes, and CRM golden dataset
+
+Future modules should add a plugin class and register it in `plugin-registry.ts`. They should not add one-off setup logic directly to the wizard.
+
+Safety rules:
+
+- Plugins cannot bypass Auth.js setup route protection.
+- Reset scopes must declare destructive behavior and affected tables.
+- CSV templates must declare ownership to avoid duplicate file contracts.
+- Seed tasks must be idempotent before execution is exposed.