# Task D.7.2 - Setup Readiness and Verification APIs ## Objective Implement the first non-destructive setup API slice for ALLA OS Initial Setup: readiness checks, verification checks, and report contracts. This slice must not run destructive reset logic or commit seed/import data. ## Files To Review - `AGENTS.md` - `plans/task-d.7.md` - `plans/task-d.7.1.md` - `docs/implementation/task-d7-initial-system-setup-audit.md` - `docs/setup/seed-matrix.md` - `docs/setup/setup-wizard-blueprint.md` - `docs/setup/setup-state-machine.md` - `docs/setup/verification-matrix.md` - `docs/setup/reset-reseed-matrix.md` - `src/db/schema.ts` - `src/features/foundation/storage/**` - `src/features/foundation/document-sequence/**` - `src/features/foundation/document-template/**` - `src/features/foundation/pdf-generator/**` - `src/features/foundation/approval/**` - `src/features/foundation/master-options/**` - `src/features/crm/reports/**` - `src/lib/auth/session.ts` - `src/lib/auth/crm-access.ts` ## Implementation Scope - Create setup feature API contracts: - `src/features/setup/api/types.ts` - `src/features/setup/api/service.ts` - `src/features/setup/api/queries.ts` - Create read-only setup server services: - `src/features/setup/server/readiness.service.ts` - `src/features/setup/server/verification.service.ts` - Create thin route handlers: - `src/app/api/setup/readiness/route.ts` - `src/app/api/setup/verify/route.ts` - Implement structured check result types: - `PASS` - `WARNING` - `FAIL` - Implement checks from `docs/setup/verification-matrix.md` that can safely run without mutating production data. - For storage smoke test, either use an explicitly temporary setup key and cleanup immediately or mark as warning when provider does not support safe smoke test yet. - Return actionable `suggestedFix` values without leaking secrets or raw SQL errors. ## Out Of Scope - Final Setup Wizard UI. - CSV template generator. - CSV preview/import commit engine. - Seed execution. - Destructive reset/reseed APIs. - Setup state persistence tables. - Migrations for `setup_runs` or `seed_manifests`. - Changing existing production CRM behavior. ## Acceptance Criteria - `GET /api/setup/readiness` returns readiness report with environment, database, migration, storage, PDF, and optional email checks. - `POST /api/setup/verify` returns verification report for a selected organization or current active organization. - Route handlers are thin and call setup server services. - All checks return consistent structured result objects. - Checks use existing foundation services where available. - No production data is created, updated, or deleted except safe temporary storage smoke-test object if explicitly implemented. - Unauthorized users cannot access setup reports. - Relevant lint/typecheck passes or failures are documented. ## Risk Notes - Migration status detection may need a conservative fallback if Drizzle metadata table differs by environment. - Storage smoke testing is partly non-transactional; if cleanup fails, the API must report a warning with the storage key. - PDF/template checks should inspect existing template rows and mappings, not render or persist PDFs in this slice. - Email checks should remain optional unless a first-class provider configuration is added. --- # Future Slices --- # Implementation Log ## 2026-07-02 - Readiness and verification APIs implemented - Added setup API contracts under `src/features/setup/api/`. - Added read-only setup services under `src/features/setup/server/`. - Added protected route handlers: - `GET /api/setup/readiness` - `POST /api/setup/verify` - Verification: - `npm run typecheck` passed. - `npx oxlint src/features/setup src/app/api/setup` passed. - `npm run lint` still fails on pre-existing unrelated repo lint issues outside this task. - Implementation note: `docs/implementation/task-d72-setup-readiness-verification-apis.md` ## Task D.7.3 - CSV Template Generator Static Template Pack Objective: create checked-in `setup/templates/*.csv` files and optional route to download them. Scope: - Generate templates from `docs/setup/csv-template-spec.md`. - Include headers and sample rows. - Mark unsupported templates in docs only, not importable packs. Out scope: - CSV parser. - CSV commit import. Acceptance criteria: - Supported templates exist under `setup/templates/`. - Each template has required headers and one safe sample row. - Template docs match checked-in files. ## Task D.7.4 - CSV Preview Validation Engine Objective: implement reusable CSV parser, validation, relationship resolution, duplicate detection, and preview report. Scope: - `src/features/setup/server/csv-import.service.ts` - preview-only API route - validation from `docs/setup/import-mapping.md` Out scope: - DB commit writes. - rollback. Acceptance criteria: - Preview classifies imported/updated/skipped/error candidates. - Unsupported templates are blocked with clear reason. ## Task D.7.5 - CSV Commit Import Engine Objective: commit validated CSV imports transactionally where safe. Scope: - commit API - transaction support - upsert support - import report Out scope: - UI. - arbitrary rollback beyond failed transaction. Acceptance criteria: - Commit requires matching preview hash. - DB-only imports rollback on error. - Related feature/foundation services are reused where practical. ## Task D.7.6 - Dashboard Setup Wizard UI Objective: build dashboard-native setup wizard using existing app shell. Scope: - `src/app/dashboard/administration/setup/page.tsx` - setup wizard components under `src/features/setup/components/` - readiness, verification, CSV preview integration Out scope: - destructive reset UI. - migrations for setup state persistence unless D.7.8 completed first. Acceptance criteria: - Uses `PageContainer`. - Responsive, accessible, dark-mode compatible. - Shows progress, preview tables, validation badges, and summary report. ## Task D.7.7 - Scoped Reset and Reseed Engine Objective: implement non-production scoped reset/reseed service. Scope: - reset scopes from `docs/setup/reset-reseed-matrix.md` - safety guards - confirmation tokens - reports Out scope: - production reset workflow. Acceptance criteria: - Production destructive reset blocked. - Scope reset is organization-aware. - Storage cleanup is reported. ## Task D.7.8 - Seed Manifest and Setup State Persistence Objective: add persistent setup run and seed manifest tracking. Scope: - schema/migrations for `setup_runs`, `setup_run_steps`, `seed_manifests`, `seed_manifest_items` - state transitions from `docs/setup/setup-state-machine.md` - manifest behavior from `docs/setup/seed-version-manifest.md` Out scope: - new business seed behavior. Acceptance criteria: - Setup can resume. - Seed packages are versioned and checksummed. - Completion report is persisted.