ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
fdd3a85b64
TenantAtlas/specs/169-action-surface-v11/quickstart.md
ahmido 37c6d0622c feat: implement spec 169 action surface contract v1.1 (#200) 
## 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
2026-03-30 09:21:39 +00:00

3.5 KiB
Raw Blame History

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

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

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

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

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.