create-nevela 0.4.3 → 0.5.0

package/README.md

@@ -28,6 +28,8 @@ php nevela dev
 
 Open http://localhost:3000/sign-in and sign in as `admin@example.com` with the password `password`. That starter account is in your local database only; add your own with `php artisan nevela:user`.
 
+The app starts with an administrator and ten sample users (two editors, eight users), in your local database only, so its Users and Roles screens have something to show. Leave the samples out with `--no-sample-users`.
+
 Add your first resource, from the same folder:
 
 ```sh

package/index.mjs

@@ -29,6 +29,10 @@ const DOCS = 'https://nevela-docs.vercel.app';
  * The account every new app starts with, so there is something to sign in as straight
  * away. It is created in the app's local database, never in code or a migration, so it
  * does not follow the app to a server.
+ *
+ * It is the app's administrator. Ten sample users are made beside it, with the same
+ * password: two editors and eight users, so the Users screen, the roles and what each
+ * of them is allowed to see have something to show on the first run.
  */
 const ADMIN = { name: 'Admin', email: 'admin@example.com', password: 'password' };
 
@@ -76,7 +80,8 @@ const HELP = `  Create a new Nevela app: a Laravel API and a Next.js dashboard.
   ${bold('Options')}
     --pm <pnpm|npm|yarn|bun>   Package manager for the dashboard. Default: the one you ran this with.
     --no-install               Don't install the dashboard's dependencies.
-    --no-user                  Don't create the starter admin account.
+    --no-user                  Don't create the starter admin account, or the sample users.
+    --no-sample-users          Create the admin only, without the ten sample users.
     --fast                     Leave out PHPUnit, Pint and Laravel's other development packages.
                                About a third quicker. Add them later: cd apps/api && composer install
     --no-git                   Don't run git init.
@@ -188,7 +193,7 @@ async function step(label, work) {
 }
 
 function parseArgs(argv) {
-  const options = { name: undefined, pm: undefined, install: true, user: true, git: true, yes: false, bundledPackage: false, devTools: true };
+  const options = { name: undefined, pm: undefined, install: true, user: true, samples: true, git: true, yes: false, bundledPackage: false, devTools: true };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '-h' || arg === '--help') {
@@ -201,6 +206,7 @@ function parseArgs(argv) {
     } else if (arg === '-y' || arg === '--yes') options.yes = true;
     else if (arg === '--no-install') options.install = false;
     else if (arg === '--no-user') options.user = false;
+    else if (arg === '--no-sample-users') options.samples = false;
     else if (arg === '--no-git') options.git = false;
     else if (arg === '--no-dev-tools' || arg === '--fast') options.devTools = false;
     else if (arg === '--bundled-package') options.bundledPackage = true;
@@ -279,7 +285,7 @@ function write(file, contents) {
   fs.writeFileSync(file, contents);
 }
 
-function writeRootFiles(root, { name, title, pm, admin }) {
+function writeRootFiles(root, { name, title, pm, admin, samples }) {
   write(path.join(root, 'package.json'), `${JSON.stringify({
     name,
     version: '0.1.0',
@@ -313,13 +319,15 @@ To check the app at any time (versions, migrations, users, and whether the dashb
 php nevela status
 \`\`\`
 ${admin ? `
-The app starts with one account, in your local database only:
+The app starts with an administrator, in your local database only:
 
 | | |
 |---|---|
 | Email | \`${admin.email}\` |
 | Password | \`${admin.password}\` |
-` : ''}
+${samples ? `
+Ten sample users are there as well, with the same password: two editors and eight users, one of them switched off. They are under **Users** in the dashboard, and what each role may do is under **Roles**. Delete them before real use.
+` : ''}` : ''}
 Everything else runs from this folder too, with \`php nevela\`:
 
 \`\`\`sh
@@ -633,7 +641,7 @@ async function main() {
   // `nevela upgrade` compares against these to tell the files you changed from the ones
   // you didn't, so an update never overwrites your work.
   write(path.join(web, '.nevela.json'), `${JSON.stringify(templateRecord(VERSION), null, 4)}\n`);
-  writeRootFiles(root, { name, title, pm, admin: options.user ? ADMIN : null });
+  writeRootFiles(root, { name, title, pm, admin: options.user ? ADMIN : null, samples: options.user && options.samples });
   const packages = options.install ? start(pm, ['install'], { cwd: web }) : null;
 
   const tokens = await step('Creating the Laravel app', async (progress) => {
@@ -689,13 +697,16 @@ async function main() {
   });
 
   let admin = false;
+  let samples = false;
   await step('Setting up the database', () => {
     // One artisan process for the app key, Sanctum's migration, the generated files, the
-    // migrations and the starter account: each separate call would start Laravel again.
-    const account = options.user && tokens ? [`--name=${ADMIN.name}`, `--email=${ADMIN.email}`, `--password=${ADMIN.password}`] : [];
+    // migrations, the starter account and the sample users: each separate call would
+    // start Laravel again.
+    const account = options.user && tokens ? [`--name=${ADMIN.name}`, `--email=${ADMIN.email}`, `--password=${ADMIN.password}`, ...(options.samples ? [] : ['--no-sample-users'])] : [];
     const setup = run('php', ['artisan', 'nevela:setup', ...account], { cwd: api, allowFailure: true });
     if (setup.ok) {
       admin = account.length > 0;
+      samples = admin && options.samples;
       return;
     }
     // 2: the app is set up and only the starter account could not be created.
@@ -707,7 +718,7 @@ async function main() {
     run('php', ['artisan', 'vendor:publish', '--tag=sanctum-migrations', '--no-interaction'], { cwd: api });
     run('php', ['artisan', 'nevela:generate'], { cwd: api });
     run('php', ['artisan', 'migrate', '--force', '--no-interaction'], { cwd: api });
-    if (account.length) admin = run('php', ['artisan', 'nevela:user', ...account], { cwd: api, allowFailure: true }).ok;
+    if (account.length) admin = run('php', ['artisan', 'nevela:user', ...account.filter((arg) => arg !== '--no-sample-users')], { cwd: api, allowFailure: true }).ok;
   });
 
   let installed = false;
@@ -741,7 +752,10 @@ async function main() {
   if (admin) {
     console.log(`\n    Email      ${bold(ADMIN.email)}`);
     console.log(`    Password   ${bold(ADMIN.password)}\n`);
-    console.log(`  ${dim(`That account is in this app's local database only. Add your own: ${nevela} user`)}`);
+    console.log(`  ${dim(`That account is the administrator, and is in this app's local database only. Add your own: ${nevela} user`)}`);
+    if (samples) {
+      console.log(`  ${dim(`Ten sample users are there too, with the same password: 2 editors and 8 users. See them under Users, and what each may do under Roles.`)}`);
+    }
   }
   console.log(`\n  Add your first resource: ${dim(`${nevela} resource Product --fields="name:string, price:money"`)}`);
   console.log(`  Check the app: ${dim(`${nevela} status`)}   Upgrade it later: ${dim(`${nevela} upgrade`)}   Everything: ${dim(nevela)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevela",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Create a new Nevela app: a Laravel API and a Next.js dashboard from one resource description.",
   "type": "module",
   "bin": {

package/template/laravel/config/nevela.php

@@ -24,6 +24,18 @@ return [
     'prefix' => 'api',
     'middleware' => ['api', 'auth:sanctum'],
 
+    /*
+    | Permissions of your own, beside the ones every resource gets (products.view,
+    | products.create, products.edit, products.delete) and the built-in users.* and roles.*.
+    | They appear on the dashboard's Roles screen, and you check one anywhere in Laravel
+    | with `$user->can('reports.view')`. Actions are any of: create, view, edit, delete.
+    |
+    |   'permissions' => [
+    |       'reports' => ['name' => 'Reports', 'actions' => ['view']],
+    |   ],
+    */
+    'permissions' => [],
+
     /*
     | Signing in. Every endpoint is under {prefix}/auth. Email and password is always
     | available; the rest can be switched off here. A method that is off is refused by the
@@ -74,8 +86,11 @@ return [
         */
         'attempts_per_address' => 300,
 
-        /* The role a self-registered account starts with. Null leaves the column alone. */
-        'default_role' => null,
+        /*
+        | The role a self-registered account starts with. USER allows nothing beyond the
+        | person's own account, which is what makes open sign-up safe. Null gives no role.
+        */
+        'default_role' => 'USER',
 
         /*
         | Where the dashboard is, for the links in emails and for passkeys, which are tied

package/template/laravel/database/migrations/2026_10_06_000000_create_nevela_access_tables.php

@@ -0,0 +1,79 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Str;
+use Nevela\Laravel\Models\Role;
+
+// Roles and permissions, and switching an account off.
+//
+// Until now every signed-in user could do everything. So that upgrading an app changes
+// nothing about who can do what, every user it already has is made an ADMIN here. Give
+// them narrower roles afterwards, from the dashboard's Users screen.
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('nevela_roles', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->string('name', 80)->unique();
+            $table->string('description', 500)->nullable();
+            // A JSON list of grants: permissions, and patterns such as "products.*".
+            $table->text('grants');
+            // One the app depends on: it can be edited, and not renamed or deleted.
+            $table->boolean('is_system')->default(false);
+            $table->timestamps();
+        });
+
+        Schema::create('nevela_role_user', function (Blueprint $table) {
+            $table->foreignUuid('role_id')->constrained('nevela_roles')->cascadeOnDelete();
+            // A string, so it holds a numeric id or a UUID, whichever the app's users have.
+            $table->string('user_id');
+            $table->primary(['role_id', 'user_id']);
+            $table->index('user_id');
+        });
+
+        $model = config('auth.providers.users.model');
+        $user = is_string($model) && class_exists($model) ? new $model : null;
+        $users = $user?->getTable() ?? 'users';
+        $key = $user?->getKeyName() ?? 'id';
+
+        if (Schema::hasTable($users) && ! Schema::hasColumn($users, 'active')) {
+            Schema::table($users, function (Blueprint $table) {
+                // False: the account can't sign in, and is signed out everywhere.
+                $table->boolean('active')->default(true);
+            });
+        }
+
+        $now = now();
+        $admin = null;
+        foreach (Role::defaults() as $role) {
+            $id = (string) Str::uuid();
+            DB::table('nevela_roles')->insert([
+                'id' => $id,
+                'name' => $role['name'],
+                'description' => $role['description'],
+                'grants' => json_encode($role['grants']),
+                'is_system' => true,
+                'created_at' => $now,
+                'updated_at' => $now,
+            ]);
+            $admin ??= $role['name'] === Role::ADMIN ? $id : null;
+        }
+
+        if ($admin !== null && Schema::hasTable($users)) {
+            DB::table($users)->orderBy($key)->select($key)->chunk(500, function ($rows) use ($admin, $key) {
+                DB::table('nevela_role_user')->insert($rows->map(fn ($row) => ['role_id' => $admin, 'user_id' => (string) $row->{$key}])->all());
+            });
+        }
+    }
+
+    public function down(): void
+    {
+        // The "active" column stays: an app may have had one of its own before this ran.
+        Schema::dropIfExists('nevela_role_user');
+        Schema::dropIfExists('nevela_roles');
+    }
+};

package/template/laravel/src/Access/Access.php

@@ -0,0 +1,168 @@
+<?php
+
+namespace Nevela\Laravel\Access;
+
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Models\Role;
+use WeakMap;
+
+/**
+ * Who holds which roles, and what those come to.
+ *
+ * Laravel's gate asks here for any ability shaped like a permission ("products.view"), so
+ * `$user->can('products.view')`, `Gate::authorize('users.edit')` and `@can` all work, and a
+ * generated policy is one line per action.
+ */
+final class Access
+{
+    /** @var WeakMap<object, list<string>>|null Grants per user object, so a request asks the database once. */
+    private static ?WeakMap $grants = null;
+
+    private static bool $ready = false;
+
+    /**
+     * Whether the roles tables exist. Before an upgraded app has run its migrations they
+     * don't, and until then everyone may do everything, as they could before.
+     */
+    public static function ready(): bool
+    {
+        // Only "yes" is remembered: the tables can appear later in the same process.
+        return self::$ready = self::$ready || Schema::hasTable('nevela_roles');
+    }
+
+    /**
+     * The grants a user holds, across all their roles. Patterns are kept as they are:
+     * give the result to Permissions::granted(), and don't compare strings.
+     *
+     * @return list<string>
+     */
+    public static function grantsFor(mixed $user): array
+    {
+        if (! is_object($user)) {
+            return [];
+        }
+        if (! self::ready()) {
+            return ['*'];
+        }
+        self::$grants ??= new WeakMap;
+        if (isset(self::$grants[$user])) {
+            return self::$grants[$user];
+        }
+        if (! self::active($user)) {
+            return self::$grants[$user] = [];
+        }
+
+        $grants = [];
+        foreach (self::rolesOf($user) as $role) {
+            array_push($grants, ...$role->grants);
+        }
+
+        return self::$grants[$user] = array_values(array_unique($grants));
+    }
+
+    public static function allows(mixed $user, string $permission): bool
+    {
+        return Permissions::granted(self::grantsFor($user), $permission);
+    }
+
+    /** An administrator: someone whose roles together come to everything. */
+    public static function isAdmin(mixed $user): bool
+    {
+        return Permissions::hasAll(self::grantsFor($user));
+    }
+
+    /** False when the account has been switched off. An app with no such column has no such thing. */
+    public static function active(mixed $user): bool
+    {
+        $attributes = method_exists($user, 'getAttributes') ? $user->getAttributes() : [];
+
+        // Only an explicit "no" switches an account off: a column with nothing in it doesn't.
+        return ! isset($attributes['active']) || (bool) $attributes['active'];
+    }
+
+    /** @return \Illuminate\Database\Eloquent\Collection<int, Role> */
+    public static function rolesOf(mixed $user)
+    {
+        return Role::query()
+            ->whereIn('id', DB::table('nevela_role_user')->where('user_id', (string) $user->getAuthIdentifier())->select('role_id'))
+            ->orderBy('name')
+            ->get();
+    }
+
+    /**
+     * Replace a user's roles.
+     *
+     * @param  list<string>  $roleIds
+     */
+    public static function assign(mixed $user, array $roleIds): void
+    {
+        $id = (string) $user->getAuthIdentifier();
+        DB::transaction(function () use ($id, $roleIds) {
+            DB::table('nevela_role_user')->where('user_id', $id)->delete();
+            $rows = array_map(fn (string $role) => ['role_id' => $role, 'user_id' => $id], array_values(array_unique($roleIds)));
+            if ($rows !== []) {
+                DB::table('nevela_role_user')->insert($rows);
+            }
+        });
+        self::forget();
+    }
+
+    /** Give a user one role by name, on top of what they have. False when there is no such role. */
+    public static function grant(mixed $user, string $roleName): bool
+    {
+        if (! self::ready()) {
+            return false;
+        }
+        $role = Role::query()->whereRaw('lower(name) = ?', [mb_strtolower($roleName)])->first();
+        if (! $role) {
+            return false;
+        }
+        DB::table('nevela_role_user')->insertOrIgnore(['role_id' => $role->id, 'user_id' => (string) $user->getAuthIdentifier()]);
+        self::forget();
+
+        return true;
+    }
+
+    /**
+     * How many administrators can still sign in, leaving out `$except`.
+     * The last one can't be removed, switched off or given a lesser role.
+     *
+     * Counted here as holding one role that comes to everything (ADMIN, or one like it).
+     * Someone whose lesser roles happen to add up to everything isn't relied on to be the
+     * app's last way in.
+     */
+    public static function otherAdmins(mixed $except = null): int
+    {
+        $model = Account::model();
+        $instance = new $model;
+        $table = $instance->getTable();
+        $key = $instance->getKeyName();
+        $hasActive = Schema::hasColumn($table, 'active');
+
+        $all =Role::query()->get()->filter(fn (Role $role) => Permissions::hasAll($role->grants))->pluck('id')->all();
+        $ids = DB::table('nevela_role_user')->whereIn('role_id', $all)->distinct()->pluck('user_id')->all();
+        if ($except !== null) {
+            $ids = array_values(array_diff($ids, [(string) $except->getAuthIdentifier()]));
+        }
+        if ($ids === []) {
+            return 0;
+        }
+
+        return $model::query()->whereIn($key, $ids)->when($hasActive, fn ($query) => $query->where('active', true))->count();
+    }
+
+    /** Forget what has been worked out, after roles or who holds them change. */
+    public static function forget(): void
+    {
+        self::$grants = null;
+    }
+
+    /** For tests that build and drop the tables within one process. */
+    public static function reset(): void
+    {
+        self::$grants = null;
+        self::$ready = false;
+    }
+}

package/template/laravel/src/Access/Permissions.php

@@ -0,0 +1,271 @@
+<?php
+
+namespace Nevela\Laravel\Access;
+
+use Nevela\Laravel\Nevela;
+
+/**
+ * Every permission this app understands, and the rules for matching a grant against one.
+ *
+ * A permission is `feature.action`: "products.view", "users.edit". The feature is a
+ * resource's table, or one of the built-in ones (users, roles), or one the app adds in
+ * config/nevela.php. The action is one of create, view, edit, delete.
+ *
+ * A role holds grants, and a grant may be a pattern:
+ *
+ *   *                  everything
+ *   products.*         every action on products
+ *   *.view             viewing everything
+ *   @resources.*       every action on every resource, including ones added later
+ *   @resources.view    viewing every resource
+ *
+ * The model, the names and the matching rules are Grit's (internal/authz), so a role means
+ * the same thing in both.
+ */
+final class Permissions
+{
+    public const ACTIONS = ['create', 'view', 'edit', 'delete'];
+
+    /** @var list<array{key: string, name: string, groups: list<array{key: string, name: string, features: list<array{key: string, name: string, actions: list<string>}>}>}>|null */
+    private static ?array $catalog = null;
+
+    /**
+     * The catalog, shaped for the roles screen: modules, their groups, their features.
+     * Only the feature and the action appear in a permission; the rest is for reading.
+     *
+     * @return list<array{key: string, name: string, groups: list<array{key: string, name: string, features: list<array{key: string, name: string, actions: list<string>}>}>}>
+     */
+    public static function catalog(): array
+    {
+        if (self::$catalog !== null) {
+            return self::$catalog;
+        }
+
+        $taken = ['users' => true, 'roles' => true];
+        $modules = [[
+            'key' => 'access',
+            'name' => 'Access',
+            'groups' => [[
+                'key' => 'identity',
+                'name' => 'Identity',
+                'features' => [
+                    ['key' => 'users', 'name' => 'Users', 'actions' => self::ACTIONS],
+                    ['key' => 'roles', 'name' => 'Roles and permissions', 'actions' => self::ACTIONS],
+                ],
+            ]],
+        ]];
+
+        // One feature per resource, under the heading it has in the sidebar.
+        $groups = [];
+        foreach (Nevela::all() as $descriptor) {
+            if (isset($taken[$descriptor->table])) {
+                continue; // a resource on the users or roles table is governed by the built-in feature
+            }
+            $taken[$descriptor->table] = true;
+            $heading = trim((string) ($descriptor->group ?? '')) ?: 'Resources';
+            $groups[$heading] ??= ['key' => self::slug($heading), 'name' => $heading, 'features' => []];
+            $groups[$heading]['features'][] = ['key' => $descriptor->table, 'name' => $descriptor->pluralLabel, 'actions' => self::ACTIONS];
+        }
+        if ($groups !== []) {
+            $modules[] = ['key' => 'resources', 'name' => 'Resources', 'groups' => array_values($groups)];
+        }
+
+        // The app's own: config('nevela.permissions') = ['reports' => ['name' => 'Reports', 'actions' => ['view']]].
+        $custom = [];
+        foreach ((array) config('nevela.permissions', []) as $key => $feature) {
+            $key = is_string($key) ? $key : (string) ($feature['key'] ?? '');
+            if (! preg_match('/^[a-z][a-z0-9_]*$/', $key) || isset($taken[$key])) {
+                continue;
+            }
+            $taken[$key] = true;
+            $actions = array_values(array_intersect(self::ACTIONS, (array) ($feature['actions'] ?? self::ACTIONS)));
+            $custom[] = ['key' => $key, 'name' => (string) ($feature['name'] ?? ucfirst(str_replace('_', ' ', $key))), 'actions' => $actions ?: self::ACTIONS];
+        }
+        if ($custom !== []) {
+            $modules[] = ['key' => 'app', 'name' => 'App', 'groups' => [['key' => 'app', 'name' => 'App', 'features' => $custom]]];
+        }
+
+        return self::$catalog = $modules;
+    }
+
+    /** Forget the catalog, after the descriptors or the config change. */
+    public static function forget(): void
+    {
+        self::$catalog = null;
+    }
+
+    /**
+     * Every permission in the catalog, sorted.
+     *
+     * @return list<string>
+     */
+    public static function keys(): array
+    {
+        $keys = [];
+        foreach (self::catalog() as $module) {
+            foreach ($module['groups'] as $group) {
+                foreach ($group['features'] as $feature) {
+                    foreach ($feature['actions'] as $action) {
+                        $keys[] = "{$feature['key']}.{$action}";
+                    }
+                }
+            }
+        }
+        sort($keys);
+
+        return $keys;
+    }
+
+    /** Whether `ability` has the shape of a permission, so the gate answers for it. */
+    public static function isPermission(string $ability): bool
+    {
+        return (bool) preg_match('/^[a-z][a-z0-9_]*\.(create|view|edit|delete)$/', $ability);
+    }
+
+    /**
+     * Whether any of the grants allows `key`.
+     *
+     * @param  list<string>  $grants
+     */
+    public static function granted(array $grants, string $key): bool
+    {
+        foreach ($grants as $grant) {
+            if (is_string($grant) && self::matches($grant, $key)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Whether one grant covers one permission.
+     *
+     * A pattern is checked to its end: "products.*" covers "products.view", and "*.view"
+     * covers "products.view" and nothing else of products. Stopping at the first "*"
+     * would turn "*.view" into "everything".
+     */
+    public static function matches(string $pattern, string $key): bool
+    {
+        if ($pattern === '*' || $pattern === $key) {
+            return true;
+        }
+        $p = explode('.', $pattern);
+        $k = explode('.', $key);
+        if (count($p) !== 2 || count($k) !== 2) {
+            return false;
+        }
+        [$feature, $action] = $p;
+
+        if (str_starts_with($feature, '@')) {
+            if (! in_array($k[0], self::featuresOf(substr($feature, 1)), true)) {
+                return false;
+            }
+        } elseif ($feature !== '*' && $feature !== $k[0]) {
+            return false;
+        }
+
+        return $action === '*' || $action === $k[1];
+    }
+
+    /**
+     * The permissions a set of grants comes to, patterns resolved against the catalog.
+     * Clients are given this, so nothing outside this class has to match a pattern.
+     *
+     * @param  list<string>  $grants
+     * @return list<string>
+     */
+    public static function expand(array $grants): array
+    {
+        return array_values(array_filter(self::keys(), fn (string $key) => self::granted($grants, $key)));
+    }
+
+    /**
+     * Whether the grants come to everything there is.
+     *
+     * @param  list<string>  $grants
+     */
+    public static function hasAll(array $grants): bool
+    {
+        return in_array('*', $grants, true) || count(self::expand($grants)) === count(self::keys());
+    }
+
+    /**
+     * The requested grants that `held` does not cover. A pattern is covered only when
+     * everything it comes to is; one that comes to nothing is not.
+     *
+     * This is the ceiling: nobody hands out more than they hold.
+     *
+     * @param  list<string>  $held
+     * @param  list<string>  $requested
+     * @return list<string>
+     */
+    public static function beyond(array $held, array $requested): array
+    {
+        if (in_array('*', $held, true)) {
+            return [];
+        }
+        $beyond = [];
+        foreach ($requested as $grant) {
+            if ($grant === '*') {
+                $beyond[] = $grant;
+            } elseif (str_contains($grant, '*') || str_starts_with($grant, '@')) {
+                $keys = self::expand([$grant]);
+                $covered = $keys !== [];
+                foreach ($keys as $key) {
+                    $covered = $covered && self::granted($held, $key);
+                }
+                if (! $covered) {
+                    $beyond[] = $grant;
+                }
+            } elseif (! self::granted($held, $grant)) {
+                $beyond[] = $grant;
+            }
+        }
+
+        return $beyond;
+    }
+
+    /**
+     * Whether a grant is one the catalog understands: "*", a permission in it, or a pattern
+     * that comes to at least one. A module pattern is accepted for a module with nothing in
+     * it yet, because its point is to cover what is added later.
+     */
+    public static function understood(string $grant): bool
+    {
+        if ($grant === '*') {
+            return true;
+        }
+        if (! preg_match('/^(\*|@?[a-z][a-z0-9_]*)\.(\*|create|view|edit|delete)$/', $grant)) {
+            return false;
+        }
+        if (str_starts_with($grant, '@')) {
+            return in_array(substr(explode('.', $grant)[0], 1), ['access', 'resources', 'app'], true);
+        }
+
+        return self::expand([$grant]) !== [];
+    }
+
+    /** @return list<string> */
+    private static function featuresOf(string $module): array
+    {
+        $features = [];
+        foreach (self::catalog() as $entry) {
+            if ($entry['key'] !== $module) {
+                continue;
+            }
+            foreach ($entry['groups'] as $group) {
+                foreach ($group['features'] as $feature) {
+                    $features[] = $feature['key'];
+                }
+            }
+        }
+
+        return $features;
+    }
+
+    private static function slug(string $heading): string
+    {
+        return trim((string) preg_replace('/[^a-z0-9]+/', '-', strtolower($heading)), '-') ?: 'resources';
+    }
+}