ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
0e2adeab71
TenantAtlas/specs/084-verification-surfaces-unification/tasks.md
ahmido 0e2adeab71 feat(verification): unify verification surfaces (Spec 084) (#102) 
Implements Spec 084 (verification-surfaces-unification).

Highlights
- Unifies tenant + onboarding verification start on `provider.connection.check` (OperationRun-based, enqueue-only).
- Ensures completed blocked runs persist a schema-valid `context.verification_report` stub (DB-only viewers never show “unavailable”).
- Adds tenant embedded verification report widget with DB-only rendering + canonical tenantless “View run” links.
- Enforces 404/403 semantics for tenantless run viewing (workspace membership + tenant entitlement required; otherwise 404).
- Fixes admin panel widgets to resolve tenant from record context so Owners can start verification and recent operations renders correctly.

Tests
- Ran: `vendor/bin/sail artisan test --compact tests/Feature/Verification/ tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php tests/Feature/Onboarding/OnboardingVerificationTest.php tests/Feature/RunAuthorizationTenantIsolationTest.php tests/Feature/Filament/TenantVerificationReportWidgetTest.php tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`

Notes
- Filament v5 / Livewire v4 compatible.
- No new assets; no changes to provider registration.

Co-authored-by: Ahmed Darrazi <ahmeddarrazi@MacBookPro.fritz.box>
Reviewed-on: #102
2026-02-09 11:28:09 +00:00

161 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
description: "Task list for Spec 084 implementation"
---
# Tasks: Verification Surfaces Unification
**Input**: Design documents from `/specs/084-verification-surfaces-unification/`
**Tests**: REQUIRED (Pest) — this feature changes runtime behavior.
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: Establish a safe baseline and align on touched surfaces.
- [X] T001 Capture baseline behavior by running existing verification tests in tests/Feature/Verification/VerificationStartDedupeTest.php and tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php
- [X] T002 Identify current tenant “Verify configuration” surface implementation in app/Filament/Resources/TenantResource/Pages/ViewTenant.php and document expected deltas in specs/084-verification-surfaces-unification/quickstart.md
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Shared primitives required by ALL user stories.
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
- [X] T003 Add schema-valid stub verification report for blocked provider.connection.check runs in app/Services/Providers/ProviderOperationStartGate.php (write context.verification_report after finalizeBlockedRun)
- [X] T004 [P] Add helper to build blocked/preflight verification checks payload in app/Support/Verification/ (e.g., new BlockedVerificationReportFactory.php used by ProviderOperationStartGate)
- [X] T005 Add a non-breaking tenant-default start helper in app/Services/Verification/StartVerification.php (keep existing explicit-connection API; delegate default-connection resolution to ProviderOperationStartGate)
- [X] T006 Ensure blocked stub report includes next steps links from context.next_steps and normalized reason_code from context.reason_code in app/Support/Verification/BlockedVerificationReportFactory.php
- [X] T007 Add Pest coverage for blocked stub report invariant in tests/Feature/Verification/ (new test file asserting completed blocked provider.connection.check has context.verification_report and it validates via VerificationReportSchema)
- [X] T027 Enforce tenant entitlement for tenant-associated runs in app/Policies/OperationRunPolicy.php and app/Filament/Pages/Operations/TenantlessOperationRunViewer.php (deny-as-not-found when workspace membership or tenant entitlement is missing)
**Checkpoint**: A blocked provider.connection.check run always has a schema-valid stored report.
---
## Phase 3: User Story 1 — Verify tenant configuration consistently (Priority: P1) 🎯 MVP
**Goal**: Start verification from tenant detail view and render the latest stored report DB-only.
**Independent Test**: Trigger the tenant verify action and confirm it creates/dedupes an OperationRun and the tenant embedded viewer renders from stored run context only.
### Tests (write first)
- [X] T008 [P] [US1] Update tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php to assert tenant verify start now creates a blocked OperationRun and includes a schema-valid verification_report stub
- [X] T009 [P] [US1] Add tenant verify happy-path test in tests/Feature/Filament/ (new test file calling ViewTenant action and asserting ProviderConnectionHealthCheckJob dispatch + canonical view-run link)
- [X] T010 [P] [US1] Add tenant embedded viewer DB-only test in tests/Feature/Filament/ (new test asserting the widget/view reads OperationRun.context only; no provider calls during render)
- [X] T032 [P] [US1] Add FR-007 regression test in tests/Feature/Filament/ asserting tenant view render path never triggers synchronous verification or permission inventory persistence
### Implementation
- [X] T011 [US1] Refactor “Verify configuration” action in app/Filament/Resources/TenantResource/Pages/ViewTenant.php to start/dedupe provider.connection.check via app/Services/Verification/StartVerification.php (no synchronous Graph work)
- [X] T012 [US1] Apply UI enforcement to the tenant verify action in app/Filament/Resources/TenantResource/Pages/ViewTenant.php using App\Support\Rbac\UiEnforcement with Capabilities::PROVIDER_RUN (visible-but-disabled; server still 403)
- [X] T013 [US1] Ensure tenant verify notifications include a canonical tenantless “View run” link using App\Support\OperationRunLinks::tenantlessView in app/Filament/Resources/TenantResource/Pages/ViewTenant.php
- [X] T033 [US1] Refactor tenant list “Verify configuration” action in app/Filament/Resources/TenantResource.php to the same unified provider.connection.check start path + canonical tenantless run links
- [X] T014 [P] [US1] Create a tenant verification viewer widget class in app/Filament/Widgets/Tenant/TenantVerificationReport.php (select latest provider.connection.check run for the current tenant)
- [X] T015 [P] [US1] Create widget view resources/views/filament/widgets/tenant/tenant-verification-report.blade.php with states: empty (Start verification CTA), in-progress, completed (render filament.components.verification-report-viewer)
- [X] T016 [US1] Register the tenant verification viewer widget on the tenant view page by updating app/Filament/Resources/TenantResource/Pages/ViewTenant.php getHeaderWidgets() to include TenantVerificationReport
- [X] T017 [US1] Implement the embedded viewer “Start verification” CTA to invoke the same unified start path (StartVerification) in app/Filament/Widgets/Tenant/TenantVerificationReport.php
- [X] T018 [US1] Ensure the embedded viewer “View run” link uses OperationRunLinks::tenantlessView in app/Filament/Widgets/Tenant/TenantVerificationReport.php and resources/views/filament/widgets/tenant/tenant-verification-report.blade.php
**Checkpoint**: US1 works end-to-end using queued OperationRun and DB-only rendering.
---
## Phase 4: User Story 2 — Onboarding verify access behaves identically (Priority: P2)
**Goal**: Onboarding verification uses the same run type, dedupe/busy semantics, and viewer behavior.
**Independent Test**: Start verification in onboarding twice and assert dedupe/busy behavior and canonical links match tenant surface.
### Tests
- [X] T019 [P] [US2] Update tests/Feature/Onboarding/OnboardingVerificationTest.php to assert busy/deduped notifications link to the canonical tenantless operations viewer route
- [X] T020 [P] [US2] Add regression test ensuring onboarding verification uses provider.connection.check and stores verification_report in tests/Feature/Onboarding/OnboardingVerificationTest.php
### Implementation
- [X] T021 [US2] Ensure app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php startVerification() uses the same unified provider.connection.check start mechanism (ProviderOperationStartGate) and remains enqueue-only
- [X] T022 [US2] Ensure onboarding “View run” links remain canonical via OperationRunLinks::tenantlessView (or equivalent tenantlessOperationRunUrl) in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
- [X] T023 [US2] Confirm onboarding verification report rendering uses App\Filament\Support\VerificationReportViewer only (no external calls) in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
---
## Phase 5: User Story 3 — Use canonical run links everywhere (Priority: P3)
**Goal**: Every verification surface links to the same tenantless run viewer route, and tenantless viewing enforces workspace + tenant entitlement (404 when missing).
**Independent Test**: From both tenant and onboarding surfaces, follow “View run” and confirm it resolves to the same canonical route and is deny-as-not-found for non-entitled actors.
### Tests
- [X] T024 [P] [US3] Add canonical link assertions for tenant verify notifications in tests/Feature/Filament/ (update test from T009 to assert route name admin.operations.view)
- [X] T025 [P] [US3] Add canonical link assertions for onboarding notifications in tests/Feature/Onboarding/OnboardingVerificationTest.php
- [X] T026 [P] [US3] Add authorization test for tenantless run viewer requiring workspace membership + tenant entitlement (404 semantics) in tests/Feature/RunAuthorizationTenantIsolationTest.php
### Implementation
- [X] T028 [US3] Ensure all verification surfaces use OperationRunLinks::tenantlessView (or identical canonical route helper) in app/Filament/Resources/TenantResource/Pages/ViewTenant.php and app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
---
## Phase 6: Polish & Cross-Cutting Concerns
**Purpose**: Formatting, stability, and quickstart validation.
- [X] T034 Fix tenant page widgets to resolve tenant from record context (Admin panel) and add regression coverage for Recent operations + Start verification disabled state
- [X] T029 Run formatting on changed files using vendor/bin/sail bin pint --dirty (e.g., app/Filament/Resources/TenantResource/Pages/ViewTenant.php, app/Services/Providers/ProviderOperationStartGate.php, tests/Feature/Verification/*)
- [X] T030 Run targeted Pest suite for this feature using vendor/bin/sail artisan test --compact tests/Feature/Verification/ tests/Feature/ProviderConnections/ProviderOperationBlockedGuidanceSpec081Test.php tests/Feature/Onboarding/OnboardingVerificationTest.php tests/Feature/RunAuthorizationTenantIsolationTest.php
- [X] T031 Validate manual flows in specs/084-verification-surfaces-unification/quickstart.md and update it if any step text is now inaccurate
---
## Dependencies & Execution Order
- Phase 1 (Setup) → Phase 2 (Foundational) → user stories.
- User stories after Phase 2:
- **US1 (P1)** can proceed immediately after Phase 2.
- **US2 (P2)** can proceed after Phase 2 (independent of US1).
- **US3 (P3)** should run after US1 + US2 (to validate “every surface”).
### Dependency Graph (stories)
- Foundation → US1
- Foundation → US2
- US1 + US2 → US3
---
## Parallel Execution Examples
### US1 parallelizable tasks
- T008, T009, T010, and T032 can be developed in parallel (separate test files).
- T014 and T015 can be developed in parallel (widget class vs Blade view).
### US2 parallelizable tasks
- T019 and T020 can be developed in parallel within tests/Feature/Onboarding/.
### US3 parallelizable tasks
- T024, T025, T026 can be developed in parallel (different test targets).
---
## Implementation Strategy
### MVP First (US1)
1. Complete Phase 1–2.
2. Implement US1 tests (T008–T010, T032) → ensure they fail.
3. Implement US1 code (T011–T018, T033) → ensure tests pass.
4. Run Phase 6 tasks to format + verify.
### Incremental Delivery
- Add US2 next to remove onboarding/tenant variance.
- Finish with US3 to unify canonical links + tenantless authorization guarantees across all surfaces.
Reference in New Issue View Git Blame Copy Permalink