# 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.
