ahmido
37c6d0622c
## Summary - implement the Action Surface Contract v1.1 runtime changes for Spec 169 - add the new explicit ActionSurfaceType contract, validator/discovery updates, and enrolled surface declarations - update Filament action-surface documentation, focused guard tests, and spec artifacts for the completed feature ## Included - clickable-row vs explicit-inspect enforcement across monitoring, reporting, CRUD, and system reference surfaces - helper-first, workflow-next, destructive-last overflow ordering checks - system panel list discovery in the primary action-surface validator - Spec 169 artifacts: spec, plan, tasks, research, data model, quickstart, and logical contract ## Verification - focused Pest verification pack completed for: - tests/Feature/Guards/ActionSurfaceValidatorTest.php - tests/Feature/Guards/ActionSurfaceContractTest.php - tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php - integrated browser smoke test completed for admin-side reference surfaces: - /admin/operations - /admin/audit-log - /admin/finding-exceptions/queue - /admin/reviews - /admin/tenants ## Notes - system panel browser smoke coverage could not be exercised in the same session because /system routes require platform authentication in the integrated browser - Livewire target remains v4-compliant and no provider registration or asset strategy changes are introduced by this PR Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #200
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# Quickstart: Action Surface Contract v1.1
|
||
|
||
## Goal
|
||
|
||
Validate that the action-surface contract now governs behavior, not just declaration presence: every enrolled reference surface declares an explicit constitution-aligned `surfaceType`, the primary validator discovers the enrolled system-panel list pages, clickable-row and explicit-inspect rules are enforced, and representative `More` menus keep helpers first, workflow actions next, and destructive actions last.
|
||
|
||
## Prerequisites
|
||
|
||
1. Start Sail.
|
||
2. Ensure the database and factories are available for the current test suite.
|
||
3. Keep the current baseline exemptions intact for deferred choosers, dashboards, widgets, onboarding flows, and non-enrolled system pages.
|
||
4. Ensure representative tenant-plane and system-plane test helpers continue to work:
|
||
- tenant helper for standard resources and monitoring pages
|
||
- platform helper for system-panel pages
|
||
|
||
## Implementation Validation Order
|
||
|
||
### 1. Run low-level validator coverage
|
||
|
||
```bash
|
||
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceValidatorTest.php
|
||
```
|
||
|
||
Expected outcome:
|
||
- Missing `surfaceType` fails.
|
||
- Invalid `surfaceType` and inspect-affordance combinations fail with actionable messages.
|
||
- `PrimaryLinkColumn` requires an explicit reason when used.
|
||
|
||
### 2. Run representative rendered action-surface guards
|
||
|
||
```bash
|
||
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
|
||
```
|
||
|
||
Expected outcome:
|
||
- Clickable-row references still render `recordUrl()` and do not expose redundant lone `View` actions.
|
||
- Explicit-inspect history and queue references preserve context and do not regress to row click.
|
||
- Reporting and evidence registers remain scan-first clickable-row registries rather than being misclassified as audit surfaces.
|
||
- System-panel reference pages are discovered by the primary validator without stale baseline exemptions.
|
||
- Representative `More` menus keep helpers first, workflow actions next, destructive actions last, and do not render empty placeholder groups.
|
||
|
||
### 3. Run RBAC-aware tenant reference coverage
|
||
|
||
```bash
|
||
vendor/bin/sail artisan test --compact tests/Feature/Rbac/TenantActionSurfaceConsistencyTest.php
|
||
```
|
||
|
||
Expected outcome:
|
||
- Tenant resource row-click and overflow behavior remains aligned with disabled-vs-forbidden capability semantics.
|
||
- Existing `More`-menu placement still cooperates with RBAC visibility rules.
|
||
|
||
### 4. Format touched implementation files
|
||
|
||
```bash
|
||
vendor/bin/sail bin pint --dirty --format agent
|
||
```
|
||
|
||
Expected outcome:
|
||
- Touched PHP files follow the repo’s Pint rules.
|
||
|
||
## Manual Smoke Check
|
||
|
||
1. Open `/admin/operations` and confirm the list still opens records through row click without a redundant row-level `View` action.
|
||
2. Open `/admin/audit-log` and confirm inspection stays explicit and context-preserving rather than row-click navigation.
|
||
3. Open `/admin/finding-exceptions/queue` and confirm inspection remains explicit while decision actions stay tied to the selected record context.
|
||
4. Open `/system/ops/runs` and `/system/directory/tenants` as a platform user and confirm those pages still behave as read-only registries while now also belonging to the main validator discovery pass.
|
||
5. Confirm deferred surfaces such as chooser pages, dashboards, widgets, and runbooks remain out of scope.
|
||
|
||
## Non-Goals For This Slice
|
||
|
||
- No new database migration or persisted artifact.
|
||
- No new asset or `filament:assets` deployment change.
|
||
- No new policy or capability family.
|
||
- No new public HTTP API; the contract artifact is internal planning documentation only. |