---

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.

- [X] T001 Confirm guardrails + story priorities in specs/057-filament-v5-upgrade/spec.md
- [X] T002 [P] Record current Composer state for rollback planning in composer.json and composer.lock
- [X] 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.

- [X] T004 Create HTTP-noise guard helper in tests/Support/AssertsNoOutboundHttp.php
- [X] T005 [P] Add a Pest expectation/wrapper for HTTP guard in tests/Pest.php
- [X] 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

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

### Implementation for User Story 1

- [X] T009 [US1] Upgrade Filament to v5 in composer.json and composer.lock
- [X] T010 [US1] Remove Filament v4-only packages in composer.json and composer.lock (pepperfm/filament-json, lara-zeus/torch-filament)
- [X] 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
- [X] T011A [US1] Verify dependency upgrade does not introduce new required migrations; if it does, ensure reversibility + document in quickstart rollback/release notes
- [X] T012 [P] [US1] Replace pepperfm JSON viewer usage in resources/views/filament/infolists/entries/snapshot-json.blade.php (remove @include('filament-json::json'))
- [X] T013 [P] [US1] Introduce a first-party JSON renderer partial in resources/views/filament/partials/json-viewer.blade.php
- [X] T014 [US1] Wire snapshot JSON infolist entry to the first-party renderer in resources/views/filament/infolists/entries/snapshot-json.blade.php
- [X] 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
- [X] 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

- [X] T017 [P] [US2] Add Monitoring DB-only render test in tests/Feature/Monitoring/OperationsDbOnlyTest.php
- [X] T018 [P] [US2] Add tenant isolation test for Monitoring query scoping in tests/Feature/Monitoring/OperationsTenantScopeTest.php
- [X] T019 [P] [US2] Add Ops UX progress component DB-only test in tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php
- [X] 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

- [X] 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
- [X] T020A [US2] Audit Monitoring/Ops page actions to ensure they only authorize + enqueue work (no outbound HTTP inline) and always link to an OperationRun
- [X] T021 [US2] Ensure Operations views remain DB-only and have no side-effects (OperationRunResource + legacy page view)
- [X] T022 [US2] Audit Ops UX progress Livewire component for DB-only behavior and tenant scoping in app/Livewire/BulkOperationProgress.php
- [X] T023 [US2] Update Livewire navigation event handling for v4 (if needed) in resources/views/livewire/bulk-operation-progress.blade.php
- [X] 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
- [X] 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.

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

---

## Phase 6: Polish & Cross-Cutting Concerns

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

### Post-merge hotfixes

- [X] T033 Fix Filament Notifications JS Livewire hook ordering (prevent `TypeError: e is not a function`)
- [X] T034 Add regression test for notifications asset hook usage
- [X] T035 Swallow Livewire cancellation promise rejections in Ops UX widget poller
- [X] T036 Ensure Ops UX widget Alpine poller cleans up on unmount (avoid stale listeners / refresh loops)
- [X] T037 Fix Backup Items modal refresh loop race condition (remove BackupItems relation manager polling; reduce unnecessary refresh churn)
- [X] 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):

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

### User Story 2

Can run in parallel (example):

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

### User Story 3

Can run in parallel (example):

```text
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)
