ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/297-managed-environment-canonical-route-cutover/tasks.md
ahmido 3ec582a182 feat: retire legacy tenant route surfaces (#352) 
## Summary
- retire legacy `/admin/t` and active `/admin/tenants` product surfaces in favor of canonical workspace-scoped managed-environment routes
- centralize runtime URL generation through `ManagedEnvironmentLinks` and update intended URL handling to reject legacy tenant paths
- remove dormant tenant panel runtime, rename test helpers to the admin environment context, and add guard coverage for route/helper regressions

## Validation
- targeted Feature guard, workspace, provider connection, required permissions, and Filament test lanes run under Sail
- browser smoke coverage run for provider connection and workspace RBAC environment access flows
- formatting and diff checks completed with Pint and `git diff --check`

## Notes
- Filament remains on v5 with Livewire v4
- provider registration stays in `apps/platform/bootstrap/providers.php`
- retired tenant resource global search is disabled and destructive action confirmation rules remain unchanged

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #352
2026-05-12 23:35:03 +00:00

191 lines
20 KiB
Markdown
Raw Permalink Blame History

---
description: "Task list for Managed Environment Canonical Route Cutover & Legacy Tenant Surface Retirement"
---
# Tasks: Managed Environment Canonical Route Cutover & Legacy Tenant Surface Retirement
**Input**: Design documents from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/297-managed-environment-canonical-route-cutover/`
**Prerequisites**: `spec.md`, `plan.md`, `research.md`, `data-model.md`, `quickstart.md`, `legacy-surface-audit.md`, `contracts/managed-environment-canonical-route-contract.md`, `checklists/requirements.md`
**Tests**: Required (Pest) for route/link/intended URL/helper changes. Browser smoke is required only if visible navigation flows are touched.
**Operations**: No new `OperationRun` behavior. Existing operation links must stay workspace-scoped through the shared OperationRun link contract.
**RBAC**: Workspace membership remains role/capability authority. Managed-environment membership remains narrowing-only. Non-member/out-of-scope returns 404; established member missing capability returns 403.
**Filament / Panel Guardrails**: Filament remains v5 on Livewire v4. Provider registration remains in `apps/platform/bootstrap/providers.php`. No new panel. No asset-strategy change unless explicitly documented.
**Review Outcome**: preparation-ready
**Workflow Outcome**: keep
**Test-governance Outcome**: keep
## Test Governance Checklist
- [x] Lane assignment is named and is the narrowest sufficient proof for each changed behavior.
- [x] New or changed tests stay in the smallest honest family; browser/heavy-governance additions are explicit.
- [x] Shared helpers, factories, seeds, fixtures, provider setup, workspace context, session state, and capability defaults stay cheap by default.
- [x] Planned validation commands cover route/link/helper/intended URL changes without pulling in unrelated lane cost.
- [x] The declared surface test profile or `standard-native-filament` relief is explicit.
- [x] Any material runtime, budget, baseline, trend, or escalation note is recorded in the active spec close-out.
## Phase 1: Safety Gate And Baseline Audit
**Purpose**: Start from a clean branch and refresh repo truth before runtime edits.
- [x] T001 Run `git status --short --branch`, `git diff --stat`, and `git log -1 --oneline` in `/Users/ahmeddarrazi/Documents/projects/wt-plattform`; stop if unrelated uncommitted changes are present.
- [x] T002 Confirm the implementation branch is `297-managed-environment-canonical-route-cutover` or an isolated session branch derived from it.
- [x] T003 Review `/Users/ahmeddarrazi/Documents/projects/wt-plattform/.specify/memory/constitution.md`, this spec package, and related Specs 287, 288, 293, and 296 as context only.
- [x] T004 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/t|admin/tenants|provider-connections|required-permissions|workspaces/.*/environments|operations"`.
- [x] T005 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && rg "TenantPanelProvider|panel:\\s*'tenant'|panel:\\s*\\\"tenant\\\"|/admin/t/|/admin/tenants|TenantResource::getUrl|TenantDashboard::getUrl|TenantRequiredPermissions::getUrl|setTenantPanelContext|admin\\.operations" . --glob '!vendor' --glob '!node_modules'`.
- [x] T006 Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/297-managed-environment-canonical-route-cutover/legacy-surface-audit.md` with every active runtime, test, copy, historical, provider-specific, and allowed technical finding before editing application code.
- [x] T007 Confirm the scope boundary remains explicit: no DB/model rename, no compatibility surface, no Package Execution, no Guided Operations, no broad localization, no broad RBAC rewrite, and no TenantPanel restoration.
## Phase 2: Remove Or Permanently Neutralize TenantPanelProvider
**Goal**: Ensure the retired tenant panel cannot be reactivated as runtime code.
- [x] T008 [P] Inspect `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Providers/Filament/TenantPanelProvider.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php`, and current tests that reference `TenantPanelProvider`.
- [x] T009 Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php` to assert `TenantPanelProvider` is not registered, no `/admin/t...` route exists, and no active panel provider with `id('tenant')` exists.
- [x] T010 Delete `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Providers/Filament/TenantPanelProvider.php` if no true runtime dependency exists.
- [x] T011 If T010 is blocked by a true dependency, document the dependency in `legacy-surface-audit.md` and still guard against registration or route activation.
- [x] T012 Update tests that directly inspect the provider file so they assert registration and route behavior instead of requiring the file to exist.
- [x] T013 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php`.
## Phase 3: Establish Canonical Managed Environment Link Contract
**Goal**: Route all environment links through one canonical owner.
- [x] T014 [P] Locate existing managed-environment route/helper owners in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app` before creating a new helper.
- [x] T015 [P] Audit current route names for environment index, detail, required permissions, diagnostics, access scopes, provider connections, and workspace operations.
- [x] T016 Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php` to prove canonical link generation for index/detail/required-permissions/diagnostics/access-scopes/operations.
- [x] T017 Create or extend the bounded canonical link helper, such as `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/ManagedEnvironmentLinks.php`, only if no repo-real helper already owns this contract.
- [x] T018 Ensure every helper method receives enough workspace/environment context to avoid ambiguous cross-workspace URL generation.
- [x] T019 Add tests proving generated canonical URLs never contain `/admin/tenants` or `/admin/t/`.
- [x] T020 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php`.
## Phase 4: Replace Runtime Legacy URL Generation
**Goal**: Stop runtime links from emitting TenantResource/TenantDashboard/TenantRequiredPermissions URLs as product truth.
- [x] T021 [P] Audit runtime occurrences of `TenantResource::getUrl(...)`, `TenantDashboard::getUrl(...)`, and `TenantRequiredPermissions::getUrl(...)` under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app`.
- [x] T022 Replace environment detail links with the canonical managed-environment link helper or repo-real equivalent.
- [x] T023 Replace required-permissions links with canonical workspace/environment required-permissions URLs.
- [x] T024 Replace diagnostics/provider-health/access-scope links with canonical workspace/environment URLs where repo-real routes exist.
- [x] T025 Replace provider-connection tenant-detail backlinks with tenantless provider-connection URLs or canonical environment detail links, depending on the page owner.
- [x] T026 Replace dashboard/workspace overview/action links that still point at `/admin/tenants...` or TenantDashboard legacy routes.
- [x] T027 Ensure `OperationRunLinks` and related navigation still generate workspace-scoped operations URLs and do not reintroduce tenant-scoped operation paths.
- [x] T028 Update runtime tests around notifications, toast actions, review detail links, evidence links, decision-register links, provider connection links, required-permissions links, workspace dashboard links, governance inbox links, and tenant dashboard/back links as directly touched.
## Phase 5: Retire Active `/admin/tenants...` Product Routes
**Goal**: Remove `/admin/tenants...` as active product truth.
- [x] T029 Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php` to assert `/admin/tenants`, `/admin/tenants/{environment}`, `/admin/tenants/{environment}/edit`, and `/admin/tenants/{environment}/memberships` are not active product pages.
- [x] T030 Decide the narrowest repo-real retirement strategy for TenantResource: remove active route registration, move it out of auto-discovery, disable it as a product surface, or replace it with canonical managed-environment routing.
- [x] T031 Apply the retirement strategy to `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/TenantResource.php` and related registration/discovery owners.
- [x] T032 Update global search behavior for any retired or moved resource: globally searchable resources must have Edit/View pages, otherwise disable global search.
- [x] T033 Ensure no navigation item, table action, header action, empty-state action, notification, or redirect uses `/admin/tenants...` as an active product destination.
- [x] T034 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan route:list | rg "admin/tenants"` and classify any remaining route in `legacy-surface-audit.md`.
- [x] T035 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php`.
## Phase 6: Intended URL Legacy Rejection
**Goal**: Prevent old paths from surviving login/workspace-selection redirects.
- [x] T036 [P] Inspect `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Workspaces/WorkspaceRedirectResolver.php` and any repo-real `WorkspaceIntendedUrl` owner.
- [x] T037 Add `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php` covering retired tenant-panel URLs, retired tenant-resource URLs, legacy operations normalization, unsafe fallback, and external URL blocking.
- [x] T038 Update intended URL handling to reject `/admin/t`, `/admin/t/*`, `/admin/tenants`, `/admin/tenants/*`, `/admin/tenants/*/required-permissions`, and `/admin/tenants/*/provider-connections`.
- [x] T039 Normalize legacy `/admin/operations` to workspace-scoped operations only when a workspace is known and authorized.
- [x] T040 Fall back to workspace home or environment index when legacy URL resolution is ambiguous or unsafe.
- [x] T041 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php`.
## Phase 7: Required Permissions And Provider Connections Canonicalization
**Goal**: Keep tenant-scoped required-permissions and provider-connection URLs retired.
- [x] T042 [P] Audit `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantRequiredPermissions.php`, provider-connection resources/pages, and related tests.
- [x] T043 Update required-permissions runtime links and tests to use `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` or the repo-real canonical equivalent.
- [x] T044 Update provider-connection links and tests so provider connections remain tenantless admin resources with neutral workspace/environment scope context.
- [x] T045 Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/ProviderConnections/LegacyRedirectTest.php` so old tenant-scoped provider-connection URLs assert not-found rather than compatibility redirect.
- [x] T046 Ensure old `/admin/tenants/{environment}/required-permissions` does not return 200 and is not used in link generation.
- [x] T047 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions tests/Feature/ProviderConnections`.
## Phase 8: Rename Tenant-Panel Test Helper
**Goal**: Remove `setTenantPanelContext()` with no alias.
- [x] T048 [P] Audit every `setTenantPanelContext()` usage under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests`.
- [x] T049 Add or extend a guard that asserts `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php` does not contain `setTenantPanelContext`.
- [x] T050 Rename the helper in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Pest.php` to the selected canonical name, such as `setAdminEnvironmentContext()` or `setManagedEnvironmentContext()`.
- [x] T051 Ensure the replacement helper sets admin panel + workspace + managed-environment context and documents that no TenantPanel exists.
- [x] T052 Update every test call site to the new helper name.
- [x] T053 Do not leave a compatibility alias under `setTenantPanelContext`.
- [x] T054 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && rg "setTenantPanelContext|panel:\\s*'tenant'|panel:\\s*\\\"tenant\\\"" tests` and classify only explicit retired-behavior guards if any remain.
## Phase 9: RBAC And Access-Scope Authority Check
**Goal**: Preserve workspace-first RBAC while route/test fixtures move.
- [x] T055 Confirm tests touching managed-environment memberships do not treat `managed_environment_memberships.role` as capability authority.
- [x] T056 Update stale `change_role` or scope-role authority expectations to workspace-membership role/capability truth.
- [x] T057 Confirm provider-connection and environment access policies still enforce workspace membership first and managed-environment narrowing second.
- [x] T058 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php`.
## Phase 10: Copy Cleanup In Touched Active Surfaces
**Goal**: Avoid tenant-first product copy in files touched by this cutover.
- [x] T059 Replace tenant-first user-facing copy in touched active surfaces, including `Tenant dashboard`, `Tenant detail`, `Open tenant detail`, `Select tenant`, `Tenant scope`, `Managed tenant`, `Remove tenant`, `Restore tenant`, and `Tenant memberships`.
- [x] T060 Keep provider-specific Microsoft tenant ID copy, technical model names, migrations, historical specs, and audit historical values where correct.
- [x] T061 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && rg "Tenant dashboard|Tenant detail|Open tenant|Select tenant|Tenant scope|Remove tenant|Restore tenant|Tenant memberships" app resources lang tests`.
- [x] T062 Record every remaining touched-file hit in `legacy-surface-audit.md` as allowed, provider-specific, technical/internal, historical, or follow-up.
## Phase 11: Regression Proof Pack
**Goal**: Prove the new cutover and existing guard packs stay green.
- [x] T063 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php tests/Feature/Guards/NoActiveTenantResourceRoutesTest.php tests/Feature/Guards/ManagedEnvironmentCanonicalRouteContractTest.php tests/Feature/Workspaces/WorkspaceIntendedUrlLegacyRejectionTest.php tests/Feature/ProviderConnections/LegacyRedirectTest.php tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php tests/Feature/Spec080WorkspaceManagedTenantAdminMigrationTest.php tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php`.
- [x] T064 Run the existing Spec 288 guard pack exactly as listed in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/297-managed-environment-canonical-route-cutover/spec.md`.
- [x] T065 Run the existing Spec 293 cutover/stabilization proof if any touched tests overlap with Spec 293 seams.
- [x] T066 If visible navigation or browser flow files changed, run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php`.
## Phase 12: Broad Validation And Close-Out
**Goal**: Finish with focused broad lanes, formatting, and the required decision.
- [x] T067 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards`.
- [x] T068 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Workspaces`.
- [x] T069 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections`.
- [x] T070 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/RequiredPermissions`.
- [x] T071 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament`.
- [x] T072 Run `cd /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
- [x] T073 Run `git diff --check` from `/Users/ahmeddarrazi/Documents/projects/wt-plattform`.
- [x] T074 Update `legacy-surface-audit.md` with fixed/remaining status and allowed references.
- [x] T075 Confirm the Filament output contract: Livewire v4.0+ compliance, provider registration in `bootstrap/providers.php`, global-search handling for retired resources, destructive-action confirmation/authorization unchanged, asset strategy unchanged or deploy note added, and tests cover pages/actions/widgets through Livewire/Filament where applicable.
- [x] T076 Write the final implementation summary with commands run, deleted legacy code, retired routes, canonical replacements, remaining legacy references, test results, and one final decision string.
## Dependencies & Execution Order
- Phase 1 blocks all runtime edits.
- Phase 2 and Phase 5 are high-risk route/provider changes and should happen before broad runtime link replacement is considered complete.
- Phase 3 can begin after Phase 1 and should land before most runtime replacement work in Phase 4.
- Phase 6 depends on enough canonical route/link contract from Phase 3 to choose safe fallbacks.
- Phase 7 depends on Phase 3 and Phase 5 route decisions.
- Phase 8 can run alongside later route replacement but must finish before final guards.
- Phase 9 must run after helper/test fixture changes that might affect RBAC setup.
- Phase 10 applies only to files touched by implementation.
- Phases 11 and 12 close the proof loop.
## Parallel Execution Examples
- T008 and T014 can run in parallel because provider deletion and link helper discovery inspect different owners.
- T021 and T036 can run in parallel after Phase 1 because runtime link audit and intended URL audit touch different seams.
- T042 and T048 can run in parallel because required-permissions/provider-connection audit and helper-call-site audit are separate.
- T059 can run after any touched-file set is known; it should not begin a repo-wide localization sweep.
## Explicit Follow-Ups / Out of Scope
- Database/model rename from `Tenant` to `ManagedEnvironment`
- Broad tenant-to-environment localization sweep
- Package Execution Contract
- Guided Operations
- Microsoft Provider Refactor
- New provider abstraction or route framework
- Full-suite repair unless separately requested
Reference in New Issue View Git Blame Copy Permalink