ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9870f5d102
TenantAtlas/specs/057-filament-v5-upgrade/tasks.md

8.2 KiB
Raw Blame History

description
Task list for feature implementation

Tasks: Admin UI Stack Upgrade (Filament v5 + Livewire v4)

Input: Design documents from specs/057-filament-v5-upgrade/

Notes

  • Tests are REQUIRED for runtime behavior changes (Pest) per repo standards.
  • Monitoring → Operations must remain DB-only during render and background Livewire requests (no outbound HTTP).

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare for a safe upgrade with fast feedback.

  • T001 Confirm guardrails + story priorities in specs/057-filament-v5-upgrade/spec.md
  • T002 [P] Record current Composer state for rollback planning in composer.json and composer.lock
  • T003 [P] Record current frontend build state for rollback planning in package.json and package-lock.json (or npm lockfile)

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Shared test/validation scaffolding used by multiple stories.

  • T004 Create HTTP-noise guard helper in tests/Support/AssertsNoOutboundHttp.php
  • T005 [P] Add a Pest expectation/wrapper for HTTP guard in tests/Pest.php
  • T006 [P] Add a minimal “Filament panel boots” smoke test skeleton in tests/Feature/Filament/FilamentBootsTest.php

Checkpoint: Foundational validation utilities exist; story work can begin.

Phase 3: User Story 1 — Admin UI keeps working after upgrade (Priority: P1) 🎯 MVP

Goal: Admins can sign in and use the Filament panel post-upgrade without runtime errors.

Independent Test: php artisan test --filter=Filament passes; manual smoke sign-in + open resource list + open/edit/save.

Tests for User Story 1

  • T007 [P] [US1] Implement Filament boot smoke test assertions in tests/Feature/Filament/FilamentBootsTest.php
  • T008 [P] [US1] Add a basic auth+navigation smoke test in tests/Feature/Filament/AdminSmokeTest.php

Implementation for User Story 1

  • T009 [US1] Upgrade Filament to v5 in composer.json and composer.lock
  • T010 [US1] Remove Filament v4-only packages in composer.json and composer.lock (pepperfm/filament-json, lara-zeus/torch-filament)
  • T011 [US1] Discover and run required Filament upgrade command(s) (verify via php artisan list / Filament upgrade docs), then reconcile any generated config/view changes; completion = panel boots (T007) + auth/navigation smoke (T008) pass
  • T011A [US1] Verify dependency upgrade does not introduce new required migrations; if it does, ensure reversibility + document in quickstart rollback/release notes
  • T012 [P] [US1] Replace pepperfm JSON viewer usage in resources/views/filament/infolists/entries/snapshot-json.blade.php (remove @include('filament-json::json'))
  • T013 [P] [US1] Introduce a first-party JSON renderer partial in resources/views/filament/partials/json-viewer.blade.php
  • T014 [US1] Wire snapshot JSON infolist entry to the first-party renderer in resources/views/filament/infolists/entries/snapshot-json.blade.php
  • T015 [US1] Remove any Torch Filament-specific usage and ensure Torchlight Engine rendering still works in resources/views/filament/infolists/entries/normalized-diff.blade.php
  • T016 [US1] Update Filament panel/provider config for v5 compatibility in app/Providers/Filament/AdminPanelProvider.php

Checkpoint: Filament panel boots and core admin journeys work.

Phase 4: User Story 2 — Monitoring & Ops UX remain safe (Priority: P2)

Goal: Monitoring → Operations remains tenant-scoped and DB-only (no outbound HTTP during render or background Livewire requests).

Independent Test: Monitoring page renders with Http::fake() and asserts nothing was sent; tenant switching keeps data scoped.

Tests for User Story 2

  • T017 [P] [US2] Add Monitoring DB-only render test in tests/Feature/Monitoring/OperationsDbOnlyTest.php
  • T018 [P] [US2] Add tenant isolation test for Monitoring query scoping in tests/Feature/Monitoring/OperationsTenantScopeTest.php
  • T019 [P] [US2] Add Ops UX progress component DB-only test in tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php
  • T019A [P] [US2] Add Monitoring render side-effects test in tests/Feature/Monitoring/OperationsActionsEnqueueRunTest.php (assert no background work is enqueued during render; no outbound HTTP)

Implementation for User Story 2

  • T020 [US2] Verify Monitoring Operations table remains tenant-scoped (OperationRunResource query scoping + legacy Operations page) in app/Filament/Resources/OperationRunResource.php and app/Filament/Pages/Monitoring/Operations.php
  • T020A [US2] Audit Monitoring/Ops page actions to ensure they only authorize + enqueue work (no outbound HTTP inline) and always link to an OperationRun
  • T021 [US2] Ensure Operations views remain DB-only and have no side-effects (OperationRunResource + legacy page view)
  • T022 [US2] Audit Ops UX progress Livewire component for DB-only behavior and tenant scoping in app/Livewire/BulkOperationProgress.php
  • T023 [US2] Update Livewire navigation event handling for v4 (if needed) in resources/views/livewire/bulk-operation-progress.blade.php
  • T024 [US2] Validate polling strategy remains safe and doesn’t trigger outbound HTTP from Monitoring pages in resources/views/livewire/bulk-operation-progress.blade.php
  • T025 [US2] Validate any wire:model.live usage works correctly under Livewire v4 in resources/views/livewire/backup-set-policy-picker-table.blade.php

Checkpoint: Monitoring → Operations is DB-only, tenant-safe, and interactive.

Phase 5: User Story 3 — Deployment remains reliable (Priority: P3)

Goal: Build/deploy succeeds and rollback is documented.

Independent Test: Clean install + npm run build + php artisan test succeeds.

  • T026 [US3] Verify Vite inputs and Filament theme build still work under v5 in vite.config.js and resources/css/filament/admin/theme.css
  • T027 [US3] Ensure frontend deps remain compatible (Tailwind v4/Vite) in package.json
  • T028 [US3] Document rollback steps (Composer + assets + any required migrations) in specs/057-filament-v5-upgrade/quickstart.md

Phase 6: Polish & Cross-Cutting Concerns

  • T029 [P] Run formatting for touched files with ./vendor/bin/pint --dirty (constitution gate)
  • T030 Run targeted test suites for this feature (Filament/Monitoring/OpsUx) via tests/Feature/*
  • T031 Run full test suite gate via php artisan test (phpunit.xml)
  • T032 [P] Update specs/057-filament-v5-upgrade/research.md with final dependency decisions and any deviations

Post-merge hotfixes

  • T033 Fix Filament Notifications JS Livewire hook ordering (prevent TypeError: e is not a function)
  • T034 Add regression test for notifications asset hook usage
  • T035 Swallow Livewire cancellation promise rejections in Ops UX widget poller
  • T036 Ensure Ops UX widget Alpine poller cleans up on unmount (avoid stale listeners / refresh loops)
  • T037 Fix Backup Items modal refresh loop race condition (remove BackupItems relation manager polling; reduce unnecessary refresh churn)
  • T038 Add regression test ensuring Backup Items table does not use Livewire polling

Dependencies & Execution Order

User Story Dependencies (graph)

  • US1 (P1) → unblocks general UI usability checks
  • US2 (P2) → depends on the Filament/Livewire upgrade from US1 being in place
  • US3 (P3) → depends on US1 (dependency upgrades) and validates deploy/rollback

Recommended order: Foundational → US1 → US2 → US3 → Polish

Parallel Execution Examples

User Story 1

Can run in parallel (example):

Run together: T012 + T013
Also in flight: T009 + T010

User Story 2

Can run in parallel (example):

Draft tests: T017 + T018 + T019
Implement: T020 through T025

User Story 3

Can run in parallel (example):

Run together: T026 + T028

Implementation Strategy

MVP Scope

MVP is User Story 1 (P1): Filament v5 + Livewire v4 upgrade with the panel booting and core admin flows working.

Incremental Delivery

  1. Land Foundational helpers/tests scaffolding
  2. Land US1 (upgrade + plugin removals/replacements)
  3. Land US2 (Monitoring DB-only + tenant isolation protections)
  4. Land US3 (build/deploy + rollback)