Ahmed Darrazi e5f5832c4e refactor: keep workspace switch in topbar only

2026-03-08 01:55:28 +01:00

10 KiB

Raw Blame History

Tasks: Workspace Switch Semantic Fix

Input: Design documents from /specs/121-workspace-switch-fix/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/routes.md, quickstart.md

Tests: Tests are REQUIRED for this runtime behavior change. Use Pest feature tests via Sail. Operations: No OperationRun work is required for this feature. RBAC: No authorization model changes are planned; tasks must preserve existing workspace membership and capability behavior. Filament UI Action Surfaces: The affected surface is a topbar navigation link; no new CRUD action surface is introduced, and the top-right user menu must not duplicate workspace switching. Filament UI UX-001: No Create/Edit/View layout changes are required; preserve existing chooser and management screens.

Organization: Tasks are grouped by user story so each story remains independently testable.

Phase 1: Setup (Shared Context)

Purpose: Align implementation with the existing chooser contract before touching code.

T001 [P] Review the canonical switch-route contract in specs/121-workspace-switch-fix/contracts/routes.md and specs/121-workspace-switch-fix/research.md
T002 [P] Inspect the current broken target in resources/views/filament/partials/context-bar.blade.php and the existing canonical switch pattern in app/Providers/Filament/AdminPanelProvider.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Confirm shared workspace-switch semantics that all stories depend on.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

T003 Confirm forced-chooser and post-selection redirect semantics in app/Http/Middleware/EnsureWorkspaceSelected.php, app/Filament/Pages/ChooseWorkspace.php, app/Support/Workspaces/WorkspaceIntendedUrl.php, and app/Support/Workspaces/WorkspaceRedirectResolver.php

Checkpoint: Canonical chooser semantics are confirmed and user-story implementation can begin.

Phase 3: User Story 1 - Direct workspace switching (Priority: P1) 🎯 MVP

Goal: Make the context-bar Switch workspace action always open the canonical chooser instead of workspace management.

Independent Test: Open a real admin page with the context bar and verify that Switch workspace points to the chooser URL with forced-chooser semantics, not to /admin/workspaces.

Tests for User Story 1 ⚠️

Note

: Add or update these tests first and ensure they fail before implementation.

T004 [P] [US1] Extend tests/Feature/Monitoring/HeaderContextBarTest.php to assert the rendered Switch workspace link targets /admin/choose-workspace?choose=1 and does not target /admin/workspaces
T005 [P] [US1] Update tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php to assert the top-right user menu does not expose a Switch workspace shortcut, even when multiple workspaces exist

Implementation for User Story 1

T006 [US1] Update resources/views/filament/partials/context-bar.blade.php to route Switch workspace to ChooseWorkspace::getUrl(panel: 'admin').'?choose=1'
T016 [US1] Remove the duplicate Switch workspace user-menu action from app/Providers/Filament/AdminPanelProvider.php so the context bar is the only switch surface

Checkpoint: User Story 1 should now be independently functional and verifiable from the rendered admin topbar.

Phase 4: User Story 2 - Preserve administrative separation (Priority: P2)

Goal: Keep workspace management reachable through its dedicated admin path without mixing it into the context-switching action.

Independent Test: Verify the chooser and admin navigation still expose Manage workspaces through /admin/workspaces while Switch workspace remains chooser-only.

Tests for User Story 2 ⚠️

T007 [P] [US2] Extend tests/Feature/Workspaces/ChooseWorkspacePageTest.php to confirm authorized users still see Manage workspaces, unauthorized roles still do not, and the chooser management affordance continues to resolve to /admin/workspaces
T008 [P] [US2] Extend tests/Feature/Workspaces/WorkspaceNavigationHubTest.php to confirm navigation separation remains Switch workspace in the topbar only while Manage workspaces remains the dedicated admin navigation path to /admin/workspaces

Implementation for User Story 2

T009 [US2] If T007 or T008 expose drift, update resources/views/filament/pages/choose-workspace.blade.php and/or app/Filament/Resources/Workspaces/WorkspaceResource.php so every Manage workspaces affordance still resolves to /admin/workspaces and remains separate from chooser-only switching

Checkpoint: User Story 2 should now prove that switching and management remain semantically distinct.

Phase 5: User Story 3 - Maintain navigational coherence (Priority: P3)

Goal: Preserve existing chooser and redirect behavior so the semantic fix does not introduce loops or breadcrumb/navigation regressions.

Independent Test: Enter the chooser through the context-switch path and confirm existing forced-chooser and post-selection routing behavior remains intact.

Tests for User Story 3 ⚠️

T010 [P] [US3] Extend tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php to keep ?choose=1 forced-chooser behavior covered for intentional workspace switching
T011 [P] [US3] Extend tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php to confirm chooser post-selection routing remains unchanged after the context-bar fix

Implementation for User Story 3

T012 [US3] If T010 or T011 expose a regression, update app/Filament/Pages/ChooseWorkspace.php and/or app/Support/Workspaces/WorkspaceRedirectResolver.php so forced-chooser semantics and post-selection branching remain unchanged

Checkpoint: User Story 3 should confirm the fix changes only entry semantics, not downstream chooser behavior.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final verification and formatting for the complete change.

T013 Perform manual QA for /admin/choose-workspace?choose=1 and /admin/workspaces, confirming page title, breadcrumbs, back-navigation, link targets, and absence of a user-menu switch shortcut remain coherent across switching and management flows
T014 Run focused Pest coverage with vendor/bin/sail artisan test --compact for tests/Feature/Monitoring/HeaderContextBarTest.php, tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php, tests/Feature/Workspaces/ChooseWorkspacePageTest.php, tests/Feature/Workspaces/WorkspaceNavigationHubTest.php, tests/Feature/Workspaces/EnsureWorkspaceSelectedMiddlewareTest.php, and tests/Feature/Workspaces/ChooseWorkspaceRedirectsToChooseTenantTest.php
T015 Run vendor/bin/sail bin pint --dirty --format agent

Dependencies & Execution Order

Phase Dependencies

Setup (Phase 1): No dependencies; can start immediately.
Foundational (Phase 2): Depends on Setup completion; blocks all user stories.
User Story 1 (Phase 3): Depends on Foundational completion; this is the MVP.
User Story 2 (Phase 4): Depends on Foundational completion; can run after or in parallel with User Story 3 once User Story 1 direction is clear.
User Story 3 (Phase 5): Depends on Foundational completion; can run after or in parallel with User Story 2.
Polish (Phase 6): Depends on completion of the desired user stories.

User Story Dependencies

US1: No dependency on other stories; delivers the primary fix.
US2: Depends only on the shared chooser/management contract, not on US3.
US3: Depends only on the shared chooser contract, not on US2.

Within Each User Story

Tests should be updated first and observed failing before implementation.
Implementation follows only after the story-specific regression tests are in place.
Each story should remain independently testable when complete.

Parallel Opportunities

T001 and T002 can run in parallel.
T004 and T005 can run in parallel.
T007 and T008 can run in parallel.
T010 and T011 can run in parallel.
After Phase 2, US2 and US3 can proceed in parallel if staffed separately.

Parallel Example: User Story 1

# Launch both regression updates for the switching contract together:
Task: "Extend tests/Feature/Monitoring/HeaderContextBarTest.php to assert the rendered Switch workspace link targets /admin/choose-workspace?choose=1 and does not target /admin/workspaces"
Task: "Update tests/Feature/Workspaces/WorkspaceSwitchUserMenuTest.php to assert the top-right user menu does not expose a Switch workspace shortcut"

Parallel Example: User Story 2

# Launch management-separation regression coverage together:
Task: "Extend tests/Feature/Workspaces/ChooseWorkspacePageTest.php to confirm authorized users still see Manage workspaces on the chooser and unauthorized roles still do not"
Task: "Extend tests/Feature/Workspaces/WorkspaceNavigationHubTest.php to confirm navigation separation remains Switch workspace in the topbar only and Manage workspaces in admin navigation"

Implementation Strategy

MVP First (User Story 1 Only)

Complete Phase 1: Setup
Complete Phase 2: Foundational
Complete Phase 3: User Story 1
Validate the rendered topbar switch target
Stop and review before broader regression work if needed

Incremental Delivery

Ship the chooser-target fix in US1
Add management-separation regression protection in US2
Add chooser-flow coherence regression protection in US3
Finish with focused tests and formatting

Parallel Team Strategy

With multiple contributors:

One contributor updates the context-bar and topbar regression tests (US1)
One contributor hardens management-separation regressions (US2)
One contributor hardens chooser-flow regressions (US3)
Recombine for focused Sail test execution and Pint

Notes

[P] tasks touch different files and can be executed in parallel.
User story labels map each task to the corresponding spec story.
No migrations, no new routes, and no new dependencies are expected.
Preserve existing chooser redirect behavior unless a failing regression test proves otherwise.

10 KiB Raw Blame History