diff --git a/AGENTS.md b/AGENTS.md index 26bfb57..921e997 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,17 +13,17 @@ This repository is a Laravel package. Keep the package focused, idiomatic, and e ## Architecture - Roster stands on `refactor-circus/keystone`, the suite's shared runtime. `RosterServiceProvider` extends `RefactorCircus\Keystone\Support\PackageServiceProvider`, describes the package in `definition()` (key `roster`, `RosterServer`, authorization on by default, history guarded by `roster.audit.view`), calls `registerPackage()` right after merging config, and boots the MCP server, Cortex and the shared history route (`GET {prefix}/history`, `roster.history.index`) through the base helpers. Action events implement `RefactorCircus\Keystone\Contracts\ActionStartingEvent` / `ActionFinishedEvent`; finished events wait for the surrounding transaction to commit. -- Code lives in domain modules under `src/Domains/{Domain}` (User, Organization, Team, Invitation, Role, Permission, Impersonation, Sso, Scim, Transfer), mirroring the `mono` domain-module standard. Each domain has a `{Domain}ServiceProvider` (extending `RefactorCircus\Keystone\Support\ServiceProvider`) registered by `src/Domains/DomainServiceProvider.php`, its JSON API routes in `routes.php` (loaded with `loadApiRoutesFrom()`), any browser routes in `web.php` (`scim.php` for the SCIM protocol), and only the subdirectories it uses. +- Code lives in domain modules under `src/Domains/{Domain}` (User, Organization, Team, Invitation, Role, Permission, Impersonation, Transfer), mirroring the `mono` domain-module standard. Each domain has a `{Domain}ServiceProvider` (extending `RefactorCircus\Keystone\Support\ServiceProvider`) registered by `src/Domains/DomainServiceProvider.php`, its JSON API routes in `routes.php` (loaded with `loadApiRoutesFrom()`), any browser routes in `web.php`, and only the subdirectories it uses. Single sign-on and provisioning are not Roster's: refactor-circus/guardian adds them through the extension seams, and Roster's code never names Guardian. - Action input is a `final readonly` `{Action}Data` in the domain's `Data/` (on `RefactorCircus\Keystone\Data\Data`), never an array: fields are promoted constructor properties (camelCase of the input keys; enums for enum values; `T|Missing = new Missing` for partial updates), `rules()` lives on the Data (with any context args), and the starting/finished events that took input carry the Data (the status events carry just the reason). HTTP and MCP requests validate once: their `rules()` return the identifier rules plus `XData::rules(...context)` (identifiers first, so they win), and `persist()`/`handle()` build with `XData::fromValidated($this->validated() / $validated)` - never `XData::from()` in a request (ArchTest). Atrium controllers and other untrusted input use `XData::from($request->all(), ...context)`, which validates; code that vouches for its values uses `new XData(...)`. `tests/ArchTest.php` rejects array input on `execute()`. - API resources extend `RefactorCircus\Keystone\Http\Resources\JsonResource` and declare `schema(JsonSchema $schema)` next to `toArray()` (always-present fields `required()`, conditional ones not, `nullable()`, enum values listed; nullable enums include `null`). MCP requests answer with `(new XResource($m))->additional([...])->toStructuredResponse()` / `XResource::collection($page)->toStructuredResponse()`, and each tool declares `outputSchema()` as `XResource::structuredSchema($schema)` / `collectionSchema($schema)` plus its extra keys. `mcpTool()` in tests checks every structured answer against the tool's schema with Keystone's `Testing\StructuredSchema`, and `tests/Feature/Mcp/OutputSchemaTest.php` requires the declaration. - Models use Keystone's `DispatchesModelEvents` (one `{Entity}{Hook}Event` per Eloquent hook, soft-delete hooks only on soft-deleting models) and resolve their table with `getTable()` from `Support\Tables` (`roster.tables`, on Keystone's `Database\Tables`); migrations, pivots, `Rule::unique`/`exists` (by model class) and joins use the same keys, never literal `roster_*` names (`tests/ArchTest.php` checks with `Arch::literalTableNames()`, and that every model has a policy, in `roster.policies` or Gate-registered by its domain provider, with `Arch::modelsWithoutPolicies()`). Every Action and Impex flow step dispatches a starting and a finished event, the starting one before and the finished one after a `DB::transaction()` that holds all of its writes (side effects that must not survive a rollback - Impex signals, jobs, mail - go after it or `afterCommit`). `tests/ArchTest.php` checks all three with Keystone's `Testing\Arch` (`actionEventGaps()`, `writesOutsideTransactions()` and `modelEventGaps()` over every model); `parityGaps()` uses `Testing\Parity`, and `mcpTool()` is `Testing\McpTools::call()`. - Models are named `{Entity}Model`; their pre-domain class names (`RefactorCircus\Roster\Models\{Entity}`) are kept as morph aliases in each domain provider, so stored subject types and other stored values keep the same string. -- Authorization: `Http\Request` and `Mcp\Request` extend Keystone's request bases and use `Support\Concerns\AuthorizesWithRoster`, whose `authorize()` checks the request's `ability()`, `scope()` and `self()` through `Domains\Permission\Services\Authorizer` (Keystone's base answers guests 401). The domain request bases carry the defaults: organization requests are scoped to `organization()`, each MCP base's `rules()` returns its identifier rules (`userRules()`, `organizationRules()`, `teamRules()`, `roleRules()`, `connectionRules()`, `transferRules()`), and the User/Organization bases find deleted records with `trashedUser()` / `trashedOrganization()`; a request only overrides what differs. `Authorizer::check()` refuses impersonation-blocked permissions, then sends `{prefix}.{verb}` to the Gate policy of the model registered for the prefix (everything before the last dot) in the `Domains\Permission\Services\Resources` singleton (method = camel-cased verb, arguments `[ModelClass, $scope, $self]`); an unregistered prefix is denied, and a package resource whose model has no policy throws. `Authorizer::RESOURCES` holds only the six core resources, registered as `roster.*` by `PermissionServiceProvider::register()`; the SSO and SCIM providers register `roster.sso` / `roster.scim`, their permissions (`PermissionCatalogue`, merged into `BuiltInRoles::sync()`) and their models' Gate policies themselves in `boot()`, through the `@internal` `rosterResource()` / `rosterPermission()`. Other packages use `resource()` / `permission()`, which refuse `roster.*`. The bundled core policies (`Domains/{Domain}/Policies`, on `Support\Policies\Policy`, registered from `roster.policies` by `registerPolicies()`, which lists only core models) answer with `Authorizer::permits()`, the raw permission check. Every model has a policy. `Authorizer::check()` answers are remembered for the request and dropped whenever `Permissions` forgets anything (`generation()`) or a resource is registered (`Resources::generation()`); policies asked with a record get its organization/team from `Authorizer::parentOf()`. Writes that change one user's access call `Permissions::flushUser()`, not `flush()`; `roster.permission_cache` optionally keeps permission names and grants in the cache store, cleared by the same listener. MCP tools extend `RefactorCircus\Keystone\Mcp\Tool`; `RosterServer` extends `RefactorCircus\Keystone\Mcp\Server` and lists `Mcp\Tools\ListRosterHistoryTool`. -- Roster has no audit code beyond its Keen integration, and that only runs while Roster audits: Keystone's `Package::audits()` (refactor-circus/keen installed and `roster.audit.enabled` on; `Roster::auditing()` asks it). Then, once every provider has booted, `Support\Audit` registers what Roster knows on Keystone's `AuditHooks` (labels, snapshot extras - profile fields, role permissions, organization domains, assignment slugs - the subject picker and organization scope for Roster's events, the impersonator/transfer context for every entry, and the password column's redaction). At the same moment the SCIM domain provider registers its own `AuditHooks::context()` closure adding `scim_token` to Roster's entries only (it checks `PackageRegistry::for($event)?->key === 'roster'` itself, catches and `report()`s any throw, and returns `[]`). `viewAuditLog` is defined as global `roster.audit.view` unless the app defines it. Otherwise Keen ignores Roster's events, the history route answers 404, the history tool is not offered, and Atrium shows no history. Never add audit tables, writers or audit APIs to Roster. `RosterServiceProvider` names the `scim` and `web` route surfaces on Keystone's `Surface` either way. +- Authorization: `Http\Request` and `Mcp\Request` extend Keystone's request bases and use `Support\Concerns\AuthorizesWithRoster`, whose `authorize()` checks the request's `ability()`, `scope()` and `self()` through `Domains\Permission\Services\Authorizer` (Keystone's base answers guests 401). The domain request bases carry the defaults: organization requests are scoped to `organization()`, each MCP base's `rules()` returns its identifier rules (`userRules()`, `organizationRules()`, `teamRules()`, `roleRules()`, `transferRules()`), and the User/Organization bases find deleted records with `trashedUser()` / `trashedOrganization()`; a request only overrides what differs. `Authorizer::check()` refuses impersonation-blocked permissions, then sends `{prefix}.{verb}` to the Gate policy of the model registered for the prefix (everything before the last dot) in the `Domains\Permission\Services\Resources` singleton (method = camel-cased verb, arguments `[ModelClass, $scope, $self]`); an unregistered prefix is denied, and a package resource whose model has no policy throws. `Authorizer::RESOURCES` holds only the six core resources, registered as `roster.*` by `PermissionServiceProvider::register()` through the `@internal` `rosterResource()` (core permissions go through the `@internal` `rosterPermission()`). Other packages register their resources, permissions (`PermissionCatalogue`, merged into `BuiltInRoles::sync()`) and their models' Gate policies themselves in `boot()`, through `resource()` / `permission()`, which refuse `roster.*`; a system permission nothing registers any more is reported by `roster:sync-permissions` and kept. The bundled core policies (`Domains/{Domain}/Policies`, on `Support\Policies\Policy`, registered from `roster.policies` by `registerPolicies()`, which lists only core models) answer with `Authorizer::permits()`, the raw permission check. Every model has a policy. `Authorizer::check()` answers are remembered for the request and dropped whenever `Permissions` forgets anything (`generation()`) or a resource is registered (`Resources::generation()`); policies asked with a record get its organization/team from `Authorizer::parentOf()`. Writes that change one user's access call `Permissions::flushUser()`, not `flush()`; `roster.permission_cache` optionally keeps permission names and grants in the cache store, cleared by the same listener. MCP tools extend `RefactorCircus\Keystone\Mcp\Tool`; `RosterServer` extends `RefactorCircus\Keystone\Mcp\Server` and lists `Mcp\Tools\ListRosterHistoryTool`. +- Roster has no audit code beyond its Keen integration, and that only runs while Roster audits: Keystone's `Package::audits()` (refactor-circus/keen installed and `roster.audit.enabled` on; `Roster::auditing()` asks it). Then, once every provider has booted, `Support\Audit` registers what Roster knows on Keystone's `AuditHooks` (labels, snapshot extras - profile fields, role permissions, organization domains, assignment slugs - the subject picker and organization scope for Roster's events, the impersonator/transfer context for every entry, and the password column's redaction). Other packages add their own context with an `AuditHooks::context()` closure for Roster's entries only (it checks `PackageRegistry::for($event)?->key === 'roster'` itself, catches and `report()`s any throw, and returns `[]`). `viewAuditLog` is defined as global `roster.audit.view` unless the app defines it. Otherwise Keen ignores Roster's events, the history route answers 404, the history tool is not offered, and Atrium shows no history. Never add audit tables, writers or audit APIs to Roster. `RosterServiceProvider` names the `web` route surface on Keystone's `Surface` either way. - Atrium owns every component and style. Roster ships no stylesheet and no Blade component namespace: views use `x-atrium::*` components and the utilities safelisted in Atrium's stylesheet only, with no `