create-nevela 0.7.1 → 0.8.0

package/template/laravel/src/Generator/ResourceGenerator.php

@@ -2,6 +2,7 @@
 
 namespace Nevela\Laravel\Generator;
 
+use Nevela\Laravel\Support\Action;
 use Nevela\Laravel\Support\Descriptor;
 use Nevela\Laravel\Support\Field;
 use Nevela\Laravel\Support\Naming;
@@ -27,19 +28,64 @@ final class ResourceGenerator
     {
         $timestamp ??= date('Y_m_d_His');
         $api = GeneratedFile::TARGET_API;
+        // An adopted table is already there, made by a migration of the app's own.
+        $migration = $d->adopted ? [] : [
+            new GeneratedFile($api, "database/migrations/{$timestamp}_create_{$d->table}_table.php", $this->migration($d, $all), GeneratedFile::MODE_ONCE, "database/migrations/*_create_{$d->table}_table.php"),
+        ];
 
         return [
             new GeneratedFile($api, "app/Models/{$d->name}.php", $this->model($d, $all)),
-            new GeneratedFile($api, "database/migrations/{$timestamp}_create_{$d->table}_table.php", $this->migration($d, $all), GeneratedFile::MODE_ONCE, "database/migrations/*_create_{$d->table}_table.php"),
+            ...$migration,
             new GeneratedFile($api, "app/Http/Requests/Nevela/{$d->name}Request.php", $this->request($d, $all)),
-            new GeneratedFile($api, "app/Http/Resources/Nevela/{$d->name}Resource.php", $this->resource($d)),
+            new GeneratedFile($api, "app/Http/Resources/Nevela/{$d->name}Resource.php", $this->resource($d, $all)),
             new GeneratedFile($api, "app/Http/Controllers/Api/{$d->name}Controller.php", $this->controller($d, $all)),
             new GeneratedFile($api, "app/Policies/{$d->name}Policy.php", $this->policy($d), GeneratedFile::MODE_ONCE),
             new GeneratedFile(GeneratedFile::TARGET_WEB, 'resources/'.Naming::kebab($d->name).'.resource.ts', $this->typescript($d, $all)),
             ...$this->pages($d),
+            ...array_values(array_map(fn (Action $action) => new GeneratedFile($api, "app/Nevela/Actions/{$d->name}/{$action->className()}.php", $this->action($d, $action), GeneratedFile::MODE_ONCE), $d->actions)),
         ];
     }
 
+    /**
+     * The class an action is written in: what happens when its button is pressed. Written
+     * once and then the app's own, like a policy. Until someone fills it in it says so.
+     */
+    public function action(Descriptor $d, Action $action): string
+    {
+        $var = $d->variable();
+        $class = $action->className();
+        $path = "app/Nevela/Actions/{$d->name}/{$class}.php";
+        $asks = $action->fields === [] ? 'It asks for nothing, so $input is empty.' : 'What the person filled in, checked: '.implode(', ', array_keys($action->fields)).'.';
+        [$imports, $signature, $what] = $action->on === 'record'
+            ? ["\nuse App\\Models\\{$d->name};\n", "{$d->name} \${$var}, array \$input", "on one {$this->lower($d->label)}"]
+            : ['', 'array $input', "on {$this->lower($d->pluralLabel)} as a whole"];
+        $permission = "{$d->table}.{$action->key()}";
+
+        return <<<PHP
+        <?php
+
+        namespace App\Nevela\Actions\\{$d->name};
+        {$imports}
+        /**
+         * {$action->label}, {$what}. Generated once — this file is yours.
+         *
+         * Nevela has done the rest by the time handle() runs: the route, the "{$permission}"
+         * permission, the check that the action applies, and the validation of what was asked
+         * for. It runs inside a database transaction, so throwing undoes what it changed, and
+         * the person is told it didn't work. What it returns is the message they see.
+         */
+        class {$class}
+        {
+            /** @param array<string, mixed> \$input {$asks} */
+            public function handle({$signature}): ?string
+            {
+                throw new \LogicException('{$action->label} does nothing yet. Write it in {$path}.');
+            }
+        }
+
+        PHP;
+    }
+
     /**
      * The resources that point at this one, each with the field that does it and the name
      * the relation gets here: a Category's Products are `products`. A second field from
@@ -90,6 +136,23 @@ final class ResourceGenerator
         return Naming::snake(Naming::plural($name));
     }
 
+    /**
+     * Whether a resource's ids are integers. A relation's column, its validation and what
+     * the API sends for it all follow the resource it points at, not the one it is on.
+     *
+     * @param  list<Descriptor>  $all
+     */
+    private function hasIntIds(string $name, Descriptor $d, array $all): bool
+    {
+        foreach ([$d, ...$all] as $candidate) {
+            if ($candidate->name === $name) {
+                return $candidate->idType === 'int';
+            }
+        }
+
+        return false;
+    }
+
     /**
      * The dashboard pages for a resource, in Flare's layout: list, new, detail and edit,
      * each with its loading skeleton. They only name the descriptor — Flare's components
@@ -226,7 +289,7 @@ final class ResourceGenerator
 
         // What you type => the artisan command it runs.
         // "update" is what upgrade was called before 0.3.0; it still works.
-        \$nevela = ['resource', 'generate', 'seed', 'user', 'upgrade', 'update', 'dev', 'status', 'version', 'trash'];
+        \$nevela = ['resource', 'adopt', 'generate', 'seed', 'user', 'upgrade', 'update', 'dev', 'status', 'version', 'trash'];
         \$artisan = ['migrate', 'tinker', 'test', 'serve'];
         if (in_array(\$name, ['--version', '-v', '-V'], true)) {
             \$name = 'version';
@@ -252,6 +315,7 @@ final class ResourceGenerator
               php nevela status                check versions, migrations, users and the dashboard
               php nevela resource Product --fields="name:string, price:money" --seed
                                                add a resource, create its table, fill it
+              php nevela adopt posts           make a resource of a table you already have
               php nevela generate              regenerate after editing a descriptor
               php nevela seed Product          fill a resource with records
               php nevela user                  create someone who can sign in
@@ -303,6 +367,14 @@ final class ResourceGenerator
         $body = $names === []
             ? 'export const resources = [] as const;'
             : implode("\n", $imports)."\n\nexport { {$list} };\nexport const resources = [{$list}] as const;";
+        // What Flare's descriptor has no place for, by resource name: the actions a resource has.
+        $extras = [];
+        foreach ($all as $d) {
+            if ($d->actions !== []) {
+                $extras[$d->name]['actions'] = array_map(fn (Action $a) => ['permission' => "{$d->table}.{$a->key()}"] + $a->toArray(), $d->actions);
+            }
+        }
+        $body .= "\n\n/** What a resource has beyond its fields. Read through lib/extras.ts. */\nexport const extras: Record<string, unknown> = ".($extras === [] ? '{}' : json_encode($extras, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)).';';
         $m = self::M;
         $e = self::E;
 
@@ -387,7 +459,9 @@ final class ResourceGenerator
             $lines[] = "Route::get('{$d->slug}/_stats', [{$controller}, 'stats'])->name('{$d->slug}.stats');";
             $lines[] = "Route::get('{$d->slug}/_insights', [{$controller}, 'insights'])->name('{$d->slug}.insights');";
             $lines[] = "Route::post('{$d->slug}/_bulk', [{$controller}, 'bulk'])->name('{$d->slug}.bulk');";
-            $lines[] = "Route::apiResource('{$d->slug}', {$controller});";
+            // An integer id is digits and nothing else: anything else in its place is no record's address.
+            $where = $d->idType === 'int' ? "->where(['{$d->routeParameter()}' => '[0-9]{1,18}'])" : '';
+            $lines[] = "Route::apiResource('{$d->slug}', {$controller}){$where};";
         }
         $body = implode("\n", $lines);
         $m = self::M;
@@ -407,6 +481,61 @@ final class ResourceGenerator
         PHP);
     }
 
+    /**
+     * The routes anyone can call: only for resources with a "public" section, and only
+     * what each one's section opens. Loaded by Nevela under {prefix}/public with the api
+     * middleware and no sign-in.
+     *
+     * @param  list<Descriptor>  $all
+     */
+    public function publicRoutes(array $all): GeneratedFile
+    {
+        usort($all, fn (Descriptor $a, Descriptor $b) => strcmp($a->slug, $b->slug));
+        $controller = '\\Nevela\\Laravel\\Http\\PublicController::class';
+        $lines = [];
+        foreach ($all as $d) {
+            $public = $d->public;
+            if ($public === null) {
+                continue;
+            }
+            $more = implode('', array_map(fn (string $name) => ", '{$name}'", $public->middleware));
+            $for = "->defaults('resource', '{$d->name}')";
+            // The third part names the count. Without it Laravel keeps one per visitor for every
+            // throttled route there is, and reading a few pages would use up a form's allowance.
+            // (nevela.throttle is Laravel's throttle, counting the visitor and not the web app's server: see PublicThrottle.)
+            $throttle = fn (string $limit, string $what) => "'nevela.throttle:{$limit},{$d->slug}.{$what}:'";
+            if ($public->read !== null) {
+                $lines[] = "Route::get('{$d->slug}', [{$controller}, 'index']){$for}->middleware([{$throttle($public->readThrottle, 'read')}{$more}])->name('{$d->slug}.index');";
+                $lines[] = "Route::get('{$d->slug}/{id}', [{$controller}, 'show']){$for}->middleware([{$throttle($public->readThrottle, 'read')}{$more}])->name('{$d->slug}.show');";
+            }
+            if ($public->create !== null) {
+                $lines[] = "Route::post('{$d->slug}', [{$controller}, 'store']){$for}->middleware([{$throttle($public->createThrottle, 'create')}{$more}])->name('{$d->slug}.store');";
+                foreach ($public->create as $field) {
+                    if ($d->fields[$field]->kind === 'file') {
+                        $lines[] = "Route::put('_nevela/uploads/{$d->name}/{$field}', [{$controller}, 'upload']){$for}->defaults('field', '{$field}')->middleware([{$throttle($public->createThrottle, 'upload')}{$more}])->name('{$d->slug}.upload.{$field}');";
+                    }
+                }
+            }
+        }
+        $body = $lines === [] ? '// No resource has a "public" section, so nothing is open.' : implode("\n", $lines);
+        $m = self::M;
+        $e = self::E;
+
+        return new GeneratedFile(GeneratedFile::TARGET_API, 'routes/nevela-public.php', <<<PHP
+        <?php
+
+        use Illuminate\Support\Facades\Route;
+
+        // What anyone can call without signing in: {prefix}/public/… (default: /api/public).
+        // Written from each resource's "public" section by `php artisan nevela:generate`.
+        // A resource without one has no route here, and so nothing of it is open.
+        {$m}
+        {$body}
+        {$e}
+
+        PHP);
+    }
+
     /** @param list<Descriptor> $all */
     public function model(Descriptor $d, array $all = []): string
     {
@@ -448,6 +577,24 @@ final class ResourceGenerator
             }
         }
         $castBlock = $casts ? implode("\n", $casts) : '';
+        // Written with the model, outside its generated block: which records are public is the app's to say.
+        $scope = $d->public?->read === null ? '' : <<<PHP
+
+
+            /**
+             * Which {$this->lower($d->pluralLabel)} anyone may read, signed in or not. The public list and
+             * the public page of one both go through here. It lets nothing through until you
+             * say what may be: for instance
+             *
+             *     \$query->whereNotNull('published_at')->where('published_at', '<=', now());
+             */
+            public function scopePublicQuery(\Illuminate\Database\Eloquent\Builder \$query): void
+            {
+                \$query->whereRaw('1 = 0');
+            }
+        PHP;
+        // An integer id is Eloquent's own default: the database numbers the records.
+        [$import, $trait] = $d->idType === 'int' ? ['', ''] : ["use Illuminate\\Database\\Eloquent\\Concerns\\HasUuids;\n", "    use HasUuids;\n\n"];
         $m = self::M;
         $e = self::E;
 
@@ -456,14 +603,11 @@ final class ResourceGenerator
 
         namespace App\Models;
 
-        use Illuminate\Database\Eloquent\Concerns\HasUuids;
-        use Illuminate\Database\Eloquent\Model;
+        {$import}use Illuminate\Database\Eloquent\Model;
 
         class {$d->name} extends Model
         {
-            use HasUuids;
-
-            protected \$table = '{$d->table}';
+        {$trait}    protected \$table = '{$d->table}';
 
             {$m}
             // Deleted records go to the trash, where they can be restored for a while.
@@ -479,7 +623,7 @@ final class ResourceGenerator
             }{$relationBlock}
             {$e}
 
-            // Your own relationships, scopes and accessors go here — outside the generated block.
+            // Your own relationships, scopes and accessors go here — outside the generated block.{$scope}
         }
 
         PHP;
@@ -493,7 +637,8 @@ final class ResourceGenerator
             $c = $f->column();
             if ($f->kind === 'belongsTo') {
                 // A required parent can't be deleted while it has children; an optional one lets go of them.
-                $columns[] = "            \$table->foreignUuid('{$c}')"
+                $foreign = $this->hasIntIds((string) $f->target, $d, $all) ? 'foreignId' : 'foreignUuid';
+                $columns[] = "            \$table->{$foreign}('{$c}')"
                     .($f->required ? '' : '->nullable()')
                     .($f->unique ? '->unique()' : '->index()')
                     ."->constrained('{$this->tableOf((string) $f->target, $d, $all)}')"
@@ -503,6 +648,8 @@ final class ResourceGenerator
             }
             $line = match (true) {
                 $f->kind === 'file' => "\$table->string('{$c}', 512)",
+                // More than a text column holds on MySQL, or HTML, whose tags count against it too.
+                $f->kind === 'text' && ($f->isRich() || $f->maxLength > 65535) => "\$table->longText('{$c}')",
                 $f->kind === 'text' => "\$table->text('{$c}')",
                 $f->kind === 'int' => "\$table->integer('{$c}')",
                 $f->kind === 'float' && $f->format === 'money' => "\$table->decimal('{$c}', 12, 2)",
@@ -510,12 +657,17 @@ final class ResourceGenerator
                 $f->kind === 'boolean' => "\$table->boolean('{$c}')->default(false)",
                 $f->kind === 'date' => "\$table->date('{$c}')",
                 $f->kind === 'datetime' => "\$table->dateTime('{$c}')",
+                $f->maxLength !== null => "\$table->string('{$c}', {$f->maxLength})",
                 $f->format === 'url' => "\$table->string('{$c}', 2048)",
                 default => "\$table->string('{$c}')",
             };
             if (! $f->required) {
                 $line .= '->nullable()';
             }
+            if ($f->default !== null && $f->kind !== 'text') {
+                // (A text column can't have one on MySQL; the request supplies it there.)
+                $line = str_replace('->default(false)', '', $line).'->default('.var_export($f->default, true).')';
+            }
             if ($f->unique) {
                 $line .= '->unique()';
             } elseif ($f->kind === 'enum') {
@@ -524,6 +676,7 @@ final class ResourceGenerator
             $columns[] = "            {$line};";
         }
         $cols = implode("\n", $columns);
+        $id = $d->idType === 'int' ? '$table->id();' : "\$table->uuid('id')->primary();";
 
         return <<<PHP
         <?php
@@ -538,7 +691,7 @@ final class ResourceGenerator
             public function up(): void
             {
                 Schema::create('{$d->table}', function (Blueprint \$table) {
-                    \$table->uuid('id')->primary();
+                    {$id}
         {$cols}
                     \$table->timestamps();
                     // When a record was deleted. Until it is removed for good it sits in the trash.
@@ -617,6 +770,27 @@ final class ResourceGenerator
         }
         $ruleLines = implode("\n", $rules);
         $columnMap = implode(', ', $columns);
+        $defaults = implode(', ', array_map(fn (Field $f) => "'{$f->name}' => ".var_export($f->default, true), array_filter($d->fields, fn (Field $f) => $f->default !== null)));
+        $defaultsBlock = $defaults === '' ? '' : <<<PHP
+
+
+            /** What a field is when a create leaves it out. */
+            protected function defaults(): array
+            {
+                return [{$defaults}];
+            }
+        PHP;
+        // Only where there is one: a resource without rich text has the request it always had.
+        $rich = implode(', ', array_map(fn (Field $f) => "'{$f->name}'", array_filter($d->fields, fn (Field $f) => $f->isRich())));
+        $richBlock = $rich === '' ? '' : <<<PHP
+
+
+            /** Fields that hold HTML. It is cleaned before it is checked, so the length is that of what is kept. */
+            protected function rich(): array
+            {
+                return [{$rich}];
+            }
+        PHP;
         $m = self::M;
         $e = self::E;
 
@@ -658,7 +832,7 @@ final class ResourceGenerator
             protected function columns(): array
             {
                 return [{$columnMap}];
-            }
+            }{$richBlock}{$defaultsBlock}
             {$e}
         }
 
@@ -672,16 +846,23 @@ final class ResourceGenerator
     private function rules(Descriptor $d, Field $f, array $all = []): array
     {
         $rules = [$f->required ? "'required'" : "'nullable'"];
+        // With a default, leaving it out is saying "the usual". Sent, it is checked like any other.
+        if ($f->default !== null) {
+            array_unshift($rules, "'sometimes'");
+        }
+        // A length of the field's own takes the place of the usual one.
+        $max = fn (int $usual) => "'max:".($f->maxLength ?? $usual)."'";
         $type = match (true) {
-            $f->kind === 'belongsTo' => ["'uuid'", "Rule::exists('{$this->tableOf((string) $f->target, $d, $all)}', 'id')"],
+            // An integer id is up to 18 digits, which is as many as always fit in the column.
+            $f->kind === 'belongsTo' => [...($this->hasIntIds((string) $f->target, $d, $all) ? ["'integer'", "'digits_between:1,18'"] : ["'uuid'"]), "Rule::exists('{$this->tableOf((string) $f->target, $d, $all)}', 'id')"],
             $f->kind === 'file' => ["'string'", "'max:512'", "new \\Nevela\\Laravel\\Rules\\UploadKey('{$d->name}', '{$f->name}')"],
-            $f->format === 'email' => ["'email'", "'max:255'"],
-            $f->format === 'url' => ["'url'", "'max:2048'"],
-            $f->format === 'tel' => ["'string'", "'max:32'"],
-            $f->format === 'slug' => ["'string'", "'alpha_dash'", "'max:255'"],
+            $f->format === 'email' => ["'email'", $max(255)],
+            $f->format === 'url' => ["'url'", $max(2048)],
+            $f->format === 'tel' => ["'string'", $max(32)],
+            $f->format === 'slug' => ["'string'", "'alpha_dash'", $max(255)],
             $f->format === 'color' => ["'string'", "'regex:/^#[0-9a-fA-F]{6}$/'"],
-            $f->kind === 'string' => ["'string'", "'max:255'"],
-            $f->kind === 'text' => ["'string'", "'max:65535'"],
+            $f->kind === 'string' => ["'string'", $max(255)],
+            $f->kind === 'text' => ["'string'", $max(65535)],
             $f->kind === 'int' && $f->format === 'percent' => ["'integer'", "'between:0,100'"],
             $f->kind === 'int' => ["'integer'"],
             $f->kind === 'float' && $f->format === 'percent' => ["'numeric'", "'between:0,100'"],
@@ -699,22 +880,31 @@ final class ResourceGenerator
         return $rules;
     }
 
-    public function resource(Descriptor $d): string
+    /** @param list<Descriptor> $all */
+    public function resource(Descriptor $d, array $all = []): string
     {
         $lines = [];
         foreach ($d->fields as $f) {
-            $value = match ($f->kind) {
-                'date' => "\$this->{$f->column()}?->format('Y-m-d')",
-                'datetime' => "\$this->{$f->column()}?->toJSON()",
+            $value = match (true) {
+                $f->kind === 'date' => "\$this->{$f->column()}?->format('Y-m-d')",
+                $f->kind === 'datetime' => "\$this->{$f->column()}?->toJSON()",
+                // Cleaned again on the way out: HTML can reach a table without passing a request.
+                $f->isRich() => "\\Nevela\\Laravel\\Nevela::html(\$this->{$f->column()})",
+                // An id is a string in the API whatever it is in the database.
+                $f->kind === 'belongsTo' && $this->hasIntIds((string) $f->target, $d, $all) => "\$this->{$f->column()} === null ? null : (string) \$this->{$f->column()}",
                 default => "\$this->{$f->column()}",
             };
             $lines[] = "            '{$f->name}' => {$value},";
             if ($f->kind === 'file') {
                 // The key is what a record stores; this is what a page needs to show it.
-                $lines[] = "            '{$f->name}File' => \\Nevela\\Laravel\\Nevela::file(\$this->{$f->column()}),";
+                $lines[] = $f->private
+                    // A private file is fetched through its record, so its details say which record.
+                    ? "            '{$f->name}File' => \\Nevela\\Laravel\\Nevela::privateFile(\$this->{$f->column()}, '{$d->slug}', \$this->getKey(), '{$f->name}'),"
+                    : "            '{$f->name}File' => \\Nevela\\Laravel\\Nevela::file(\$this->{$f->column()}),";
             }
         }
         $body = implode("\n", $lines);
+        $id = $d->idType === 'int' ? '(string) $this->id' : '$this->id';
         $m = self::M;
         $e = self::E;
 
@@ -734,7 +924,7 @@ final class ResourceGenerator
             public function toArray(Request \$request): array
             {
                 return [
-                    'id' => \$this->id,
+                    'id' => {$id},
                     {$m}
         {$body}
                     {$e}
@@ -953,12 +1143,22 @@ final class ResourceGenerator
                 'unique' => $f->unique ? 'true' : null,
                 'label' => $f->label ? $j($f->label) : null,
                 'format' => in_array($f->format, ['money', 'percent', 'rating'], true) ? $j($f->format) : null,
+                'maxLength' => $f->maxLength !== null ? (string) $f->maxLength : null,
+                'default' => $f->default !== null ? $j($f->default) : null,
                 // What the migration does when the parent goes: an optional link is cleared.
                 'onDelete' => $f->kind === 'belongsTo' && ! $f->required ? '"set null"' : null,
-                // A picture is worth a column in the table; other files are not.
-                'list' => $f->isImage() ? 'true' : null,
+                // A picture is worth a column in the table; other files are not, and a private one has no thumbnail to show.
+                'list' => $f->isImage() && ! $f->private ? 'true' : null,
             ]);
-            $opts = $options ? '{ '.implode(', ', array_map(fn ($k, $v) => "{$k}: {$v}", array_keys($options), $options)).' }' : '';
+            $parts = array_map(fn ($k, $v) => "{$k}: {$v}", array_keys($options), $options);
+            if ($f->private) {
+                $parts[] = '...({ private: true } as {})';
+            }
+            if ($f->isRich()) {
+                // Flare has no word for it, so it is said in passing: the dashboard reads `rich` off the field.
+                $parts[] = '...({ rich: true } as {})';
+            }
+            $opts = $parts ? '{ '.implode(', ', $parts).' }' : '';
             $call = match (true) {
                 $f->kind === 'belongsTo' => "field.belongsTo({$j($f->target)}".($opts ? ", {$opts}" : '').')',
                 $f->kind === 'file' => "field.file({$j($f->accept)}".($opts ? ", {$opts}" : '').')',

package/template/laravel/src/Http/ActionController.php

@@ -0,0 +1,222 @@
+<?php
+
+namespace Nevela\Laravel\Http;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Gate;
+use Illuminate\Support\Facades\Validator;
+use Illuminate\Validation\ValidationException;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Action;
+use Nevela\Laravel\Support\Descriptor;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Throwable;
+
+/**
+ * A resource's own actions: what its descriptor's "actions" section names.
+ *
+ *   POST {slug}/{id}/_actions/{action}   { input }         on one record
+ *   POST {slug}/_actions/{action}        { input }         on the resource as a whole
+ *   POST {slug}/_actions/{action}        { ids, input }    a record action, on a selection
+ *
+ * One controller for every resource, like the trash: every action is reached the same
+ * way and differs only in the class that does it, App\Nevela\Actions\<Resource>\<Action>.
+ * Here is everything around that class: who may, whether it applies, whether what was
+ * asked for is valid, and what the person is told when it fails.
+ */
+final class ActionController
+{
+    /** The most records a selection can be: what the dashboard's table can select at once, with room. */
+    private const MOST = 500;
+
+    public function record(Request $request, string $slug, string $id, string $action): JsonResponse
+    {
+        [$descriptor, $definition] = $this->find($slug, $action, 'record');
+        $this->authorize($request, $descriptor, $definition);
+        $record = $this->one($descriptor, $id) ?? throw new NotFoundHttpException;
+        if (! $this->applies($descriptor, $definition, $record)) {
+            return response()->json(['error' => "{$definition->label} can't be done to this ".strtolower($descriptor->label).' as it is now.', 'code' => 'NOT_APPLICABLE'], 409);
+        }
+        $input = $this->input($request, $definition);
+
+        return $this->run($definition, function () use ($descriptor, $definition, $record, $input, $request) {
+            $message = $this->handler($descriptor, $definition)->handle($record, $input);
+
+            return ['message' => is_string($message) && $message !== '' ? $message : "{$definition->label}: done.", 'record' => $this->present($descriptor, $record, $request)];
+        });
+    }
+
+    public function collection(Request $request, string $slug, string $action): JsonResponse
+    {
+        [$descriptor, $definition] = $this->find($slug, $action, null);
+        $this->authorize($request, $descriptor, $definition);
+        $input = $this->input($request, $definition);
+
+        if ($definition->on === 'collection') {
+            return $this->run($definition, function () use ($descriptor, $definition, $input) {
+                $message = $this->handler($descriptor, $definition)->handle($input);
+
+                return ['message' => is_string($message) && $message !== '' ? $message : "{$definition->label}: done."];
+            });
+        }
+
+        // A record action, on several records at once.
+        if (! $definition->many) {
+            throw new NotFoundHttpException;
+        }
+        $ids = $request->input('ids');
+        if (! is_array($ids) || ! array_is_list($ids) || $ids === [] || count($ids) > self::MOST) {
+            return response()->json(['error' => 'Send the records as "ids": a list of 1 to '.self::MOST.'.'], 422);
+        }
+
+        return $this->run($definition, function () use ($descriptor, $definition, $input, $ids) {
+            $handler = $this->handler($descriptor, $definition);
+            $done = 0;
+            $skipped = 0;
+            foreach (array_unique(array_map('strval', array_filter($ids, 'is_scalar'))) as $id) {
+                $record = $this->one($descriptor, $id);
+                // One it no longer applies to, or that has gone, is passed over: the rest still want doing.
+                if ($record === null || ! $this->applies($descriptor, $definition, $record)) {
+                    $skipped++;
+
+                    continue;
+                }
+                $handler->handle($record, $input);
+                $done++;
+            }
+            $what = strtolower($done === 1 ? $descriptor->label : $descriptor->pluralLabel);
+
+            return [
+                'message' => "{$definition->label}: {$done} {$what}".($skipped > 0 ? ", and {$skipped} left as ".($skipped === 1 ? 'it was' : 'they were').'.' : '.'),
+                'done' => $done,
+                'skipped' => $skipped,
+            ];
+        });
+    }
+
+    /**
+     * The resource and the action an address names.
+     *
+     * @param  'record'|null  $on  Where it must be, or either
+     * @return array{Descriptor, Action}
+     */
+    private function find(string $slug, string $action, ?string $on): array
+    {
+        foreach (Nevela::all() as $descriptor) {
+            $definition = $descriptor->slug === $slug ? ($descriptor->actions[$action] ?? null) : null;
+            if ($definition !== null && ($on === null || $definition->on === $on)) {
+                return [$descriptor, $definition];
+            }
+        }
+        throw new NotFoundHttpException;
+    }
+
+    /** Its own permission, by name. Being able to edit the records is not being able to do this to them. */
+    private function authorize(Request $request, Descriptor $descriptor, Action $action): void
+    {
+        if (! $request->user()?->can("{$descriptor->table}.{$action->key()}")) {
+            throw new AccessDeniedHttpException("You don't have access to this.");
+        }
+    }
+
+    /** The record with this id, if there is one and the person may see it. */
+    private function one(Descriptor $descriptor, string $id): ?Model
+    {
+        $model = "App\\Models\\{$descriptor->name}";
+        if (! class_exists($model) || ($descriptor->idType === 'int' && ! preg_match('/^[0-9]{1,18}$/', $id))) {
+            return null;
+        }
+        $record = $model::query()->find($id);
+
+        return $record !== null && Gate::allows('view', $record) ? $record : null;
+    }
+
+    private function applies(Descriptor $descriptor, Action $action, Model $record): bool
+    {
+        $values = [];
+        foreach (array_keys($action->when) as $field) {
+            $values[$field] = $record->getAttribute($descriptor->fields[$field]->column());
+        }
+
+        return $action->applies($values);
+    }
+
+    /**
+     * What the action asked for, checked. A problem is reported against its field, the way
+     * a form's is, so the sheet can show it there.
+     *
+     * @return array<string, mixed>
+     */
+    private function input(Request $request, Action $action): array
+    {
+        $sent = $request->input('input', []);
+        $sent = is_array($sent) ? $sent : [];
+        $validator = Validator::make($sent, $action->rules());
+        $validator->after(function ($validator) use ($sent, $action) {
+            foreach (array_keys($sent) as $key) {
+                if (! isset($action->fields[$key])) {
+                    $validator->errors()->add((string) $key, 'Unknown field.');
+                }
+            }
+        });
+        if ($validator->fails()) {
+            throw new ValidationException($validator);
+        }
+
+        return $validator->validated();
+    }
+
+    private function handler(Descriptor $descriptor, Action $action): object
+    {
+        $class = "App\\Nevela\\Actions\\{$descriptor->name}\\{$action->className()}";
+        if (! class_exists($class) || ! method_exists($class, 'handle')) {
+            throw new \LogicException("{$action->label} has no class to do it. Run: php artisan nevela:generate {$descriptor->name}");
+        }
+
+        return app($class);
+    }
+
+    /**
+     * Do it, all of it or none: what the class changed in the database is undone when it
+     * throws, and the person is told that it didn't work and that nothing was changed.
+     *
+     * @param  callable(): array<string, mixed>  $do
+     */
+    private function run(Action $action, callable $do): JsonResponse
+    {
+        try {
+            return response()->json(DB::transaction($do));
+        } catch (HttpExceptionInterface|ValidationException $e) {
+            throw $e; // the class said why itself: abort(409, …), or a validation error
+        } catch (Throwable $e) {
+            report($e);
+
+            return response()->json(array_filter([
+                'error' => "{$action->label} didn't work, and nothing was changed.",
+                // Said to whoever is building the app, not to whoever is using it.
+                'detail' => config('app.debug') ? $e->getMessage() : null,
+            ]), 500);
+        }
+    }
+
+    /**
+     * The record as the API shows it, after the action: what the page it was pressed on now needs.
+     *
+     * @return array<string, mixed>|null
+     */
+    private function present(Descriptor $descriptor, Model $record, Request $request): ?array
+    {
+        $resource = "App\\Http\\Resources\\Nevela\\{$descriptor->name}Resource";
+        if (! $record->exists || ! class_exists($resource)) {
+            return null;
+        }
+        $fresh = $record->fresh();
+
+        return $fresh === null ? null : (new $resource($fresh))->resolve($request);
+    }
+}