alla-allaos-fullstack/plans/task-d.7.2.md

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.