create-nevela 0.1.4 → 0.2.1

package/package.json

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

package/project.mjs

@@ -7,6 +7,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { isNewer, satisfiesCaret } from './packagist.mjs';
 import { spawnCommand } from './shell.mjs';
 
 /** What `nevela <name>` runs: these go to `php artisan nevela:<name>`. */
@@ -64,6 +65,16 @@ export function repairManifest(manifest, latest) {
   if (typeof current === 'string' && /^\d+\.\d+(\.\d+)?$/.test(current)) {
     manifest.require['nevela/laravel'] = caret ?? `^${current.split('.').slice(0, 2).join('.')}`;
     repairs.push(`"nevela/laravel": "${current}" pinned one exact version; it is now "${manifest.require['nevela/laravel']}"`);
+    return repairs;
+  }
+
+  // Below 1.0 a caret holds the minor version: "^0.1" never reaches 0.2.0, so an update
+  // would finish having changed nothing. Updating is asking for the newest, so the range
+  // is moved to the one that has it.
+  const range = typeof current === 'string' ? /^\^(\d+)\.(\d+)(?:\.\d+)?$/.exec(current) : null;
+  if (range && caret && caret !== current && !satisfiesCaret(latest, [Number(range[1]), Number(range[2])]) && isNewer(latest, `${range[1]}.${range[2]}.0`)) {
+    manifest.require['nevela/laravel'] = caret;
+    repairs.push(`"nevela/laravel": "${current}" doesn't reach ${latest}; it is now "${caret}"`);
   }
   return repairs;
 }

package/template/laravel/composer.json

@@ -1,59 +1,61 @@
-{
-    "name": "nevela/laravel",
-    "description": "Nevela for Laravel: describe a resource once and generate its model, migration, validation, policy and REST API, plus the Next.js dashboard screens for it.",
-    "type": "library",
-    "license": "MIT",
-    "keywords": [
-        "laravel",
-        "nevela",
-        "generator",
-        "crud",
-        "rest-api",
-        "nextjs",
-        "dashboard",
-        "scaffold"
-    ],
-    "homepage": "https://nevela-docs.vercel.app",
-    "authors": [
-        {
-            "name": "Mark Cole MUKISA",
-            "homepage": "https://github.com/MarkColeMukisa"
-        }
-    ],
-    "support": {
-        "issues": "https://github.com/MarkColeMukisa/nevela/issues",
-        "source": "https://github.com/MarkColeMukisa/nevela",
-        "docs": "https://nevela-docs.vercel.app"
-    },
-    "require": {
-        "php": "^8.2",
-        "illuminate/support": "^11.0|^12.0|^13.0",
-        "illuminate/database": "^11.17|^12.0|^13.0",
-        "illuminate/http": "^11.0|^12.0|^13.0",
-        "illuminate/console": "^11.0|^12.0|^13.0"
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^11.0"
-    },
-    "suggest": {
-        "laravel/sanctum": "Required for the token sign-in endpoints and the default auth:sanctum middleware (php artisan install:api)."
-    },
-    "autoload": {
-        "psr-4": {
-            "Nevela\\Laravel\\": "src/"
-        }
-    },
-    "autoload-dev": {
-        "psr-4": {
-            "Nevela\\Laravel\\Tests\\": "tests/"
-        }
-    },
-    "extra": {
-        "laravel": {
-            "providers": [
-                "Nevela\\Laravel\\NevelaServiceProvider"
-            ]
-        }
-    },
-    "minimum-stability": "stable"
-}
+{
+    "name": "nevela/laravel",
+    "description": "Nevela for Laravel: describe a resource once and generate its model, migration, validation, policy and REST API, plus the Next.js dashboard screens for it.",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "laravel",
+        "nevela",
+        "generator",
+        "crud",
+        "rest-api",
+        "nextjs",
+        "dashboard",
+        "scaffold"
+    ],
+    "homepage": "https://nevela-docs.vercel.app",
+    "authors": [
+        {
+            "name": "Mark Cole MUKISA",
+            "homepage": "https://github.com/MarkColeMukisa"
+        }
+    ],
+    "support": {
+        "issues": "https://github.com/MarkColeMukisa/nevela/issues",
+        "source": "https://github.com/MarkColeMukisa/nevela",
+        "docs": "https://nevela-docs.vercel.app"
+    },
+    "require": {
+        "php": "^8.2",
+        "illuminate/support": "^11.0|^12.0|^13.0",
+        "illuminate/database": "^11.17|^12.0|^13.0",
+        "illuminate/http": "^11.0|^12.0|^13.0",
+        "illuminate/console": "^11.0|^12.0|^13.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^11.0"
+    },
+    "suggest": {
+        "laravel/sanctum": "Required for the token sign-in endpoints and the default auth:sanctum middleware (php artisan install:api).",
+        "ext-gd": "Optimises uploaded images: resizing, WebP and renditions. Without it images are stored as uploaded.",
+        "ext-exif": "Turns phone photos the right way up before their metadata is removed."
+    },
+    "autoload": {
+        "psr-4": {
+            "Nevela\\Laravel\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Nevela\\Laravel\\Tests\\": "tests/"
+        }
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Nevela\\Laravel\\NevelaServiceProvider"
+            ]
+        }
+    },
+    "minimum-stability": "stable"
+}

package/template/laravel/config/nevela.php

@@ -33,4 +33,74 @@ return [
     /* List defaults, matching Flare's client. */
     'per_page' => 25,
     'max_per_page' => 100,
+
+    /*
+    | File and image fields (image:image, manual:file(pdf)).
+    |
+    | Files go on a disk from config/filesystems.php and are handed out by Nevela's own
+    | route, GET {prefix}/_nevela/files/{key}, so nothing needs linking or publishing. Keys
+    | are unguessable, but anyone who has one can fetch the file: don't use these fields
+    | for documents that must stay private. If a CDN or your web server serves the disk,
+    | put its address in NEVELA_UPLOADS_URL and the API's links point there.
+    */
+    'uploads' => [
+        'disk' => env('NEVELA_UPLOADS_DISK', 'public'),
+        'url' => env('NEVELA_UPLOADS_URL'),
+
+        /* Where untouched originals are kept, so an image can be optimised again later. Never served. */
+        'originals_disk' => env('NEVELA_ORIGINALS_DISK', 'local'),
+
+        /* The largest file a field takes. */
+        'max_bytes' => 10 * 1024 * 1024,
+
+        /* Memory allowed while an image is being optimised: a phone photo needs more than PHP's usual 128M. */
+        'memory' => '512M',
+
+        /*
+        | How images are optimised. Every image field uses "default" unless it names another:
+        | image:image(product). A profile only says what differs from the default.
+        |
+        |   max         [width, height] the stored image fits inside. Add 'crop' to fill it exactly.
+        |   quality     1 to 100.
+        |   format      auto, webp, jpeg, png or avif. Auto keeps transparency and otherwise
+        |               picks the smallest.
+        |   renditions  extra sizes made alongside, by name. Ask for one by putting its name
+        |               before the extension: kettle.webp → kettle.thumb.webp
+        |   keep_original  keep the untouched upload on the originals disk.
+        |   on_error    store_original (keep the upload as it came) or reject.
+        |   max_pixels  refuse anything that would decode to more than this.
+        */
+        'profiles' => [
+            'default' => [
+                'max' => [1600, 1600],
+                'quality' => 82,
+                'format' => 'auto',
+                'renditions' => ['thumb' => [400, 400, 'crop']],
+                'keep_original' => true,
+                'on_error' => 'store_original',
+                'max_pixels' => 50_000_000,
+            ],
+
+            // A product photograph: smaller than the default, because a catalogue page shows a dozen at once.
+            'product' => [
+                'max' => [1000, 1000],
+                'quality' => 80,
+                'renditions' => ['thumb' => [300, 300, 'crop'], 'card' => [600, 600]],
+            ],
+
+            // Always square and always small, so it crops: a portrait in a round frame shouldn't letterbox.
+            'avatar' => [
+                'max' => [400, 400, 'crop'],
+                'quality' => 85,
+                'renditions' => ['thumb' => [80, 80, 'crop']],
+                'keep_original' => false,
+            ],
+
+            // A hero or cover image, where width matters more than total pixels.
+            'cover' => [
+                'max' => [2400, 1200],
+                'renditions' => ['thumb' => [600, 300, 'crop']],
+            ],
+        ],
+    ],
 ];

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

@@ -0,0 +1,38 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+// What Nevela knows about each uploaded file: where it is, how big it is, and for an
+// image, its dimensions and the smaller renditions made from it.
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('nevela_uploads', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->string('key', 512)->unique();
+            $table->string('disk');
+            $table->string('resource')->index();
+            $table->string('field');
+            $table->string('name');
+            $table->string('mime');
+            $table->unsignedBigInteger('size');
+            $table->unsignedInteger('width')->nullable();
+            $table->unsignedInteger('height')->nullable();
+            $table->json('renditions')->nullable();
+            $table->string('profile')->nullable();
+            $table->boolean('optimised')->default(false);
+            $table->string('original_key', 512)->nullable();
+            $table->unsignedBigInteger('original_size')->nullable();
+            $table->string('uploaded_by')->nullable();
+            $table->timestamps();
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('nevela_uploads');
+    }
+};

package/template/laravel/src/Console/GenerateCommand.php

@@ -61,9 +61,32 @@ final class GenerateCommand extends Command
     public static function generate(Command $command, array $targets, array $all, bool $force): int
     {
         $generator = new ResourceGenerator;
-        $files = [];
+        $byName = [];
+        foreach ($all as $descriptor) {
+            $byName[$descriptor->name] = $descriptor;
+        }
+
+        // A relation is written on both ends, so the resource a new one points at is
+        // regenerated with it: Category gains its products when Product arrives.
+        $queue = [];
         foreach ($targets as $descriptor) {
-            array_push($files, ...$generator->forResource($descriptor));
+            $queue[$descriptor->name] = $descriptor;
+            foreach ($descriptor->fields as $field) {
+                if ($field->kind !== 'belongsTo') {
+                    continue;
+                }
+                if (! isset($byName[$field->target])) {
+                    $command->components->error("{$descriptor->name}.{$field->name} belongs to {$field->target}, which doesn't exist yet. Create it first: php artisan nevela:resource {$field->target} --fields=\"name:string\"");
+
+                    return self::FAILURE;
+                }
+                $queue[$field->target] ??= $byName[$field->target];
+            }
+        }
+
+        $files = [];
+        foreach ($queue as $descriptor) {
+            array_push($files, ...$generator->forResource($descriptor, null, $all));
         }
         $files[] = $generator->routes($all);
         $files[] = $generator->registry($all);

package/template/laravel/src/Console/MakeResourceCommand.php

@@ -43,6 +43,14 @@ final class MakeResourceCommand extends Command
 
             return self::FAILURE;
         }
+        // Checked before anything is written: a relation needs the resource it points at.
+        foreach ($descriptor->fields as $field) {
+            if ($field->kind === 'belongsTo' && $field->target !== $descriptor->name && ! is_file($dir.DIRECTORY_SEPARATOR.Naming::kebab((string) $field->target).'.json')) {
+                $this->components->error("{$field->name} belongs to {$field->target}, which doesn't exist yet. Create it first: php artisan nevela:resource {$field->target} --fields=\"name:string\"");
+
+                return self::FAILURE;
+            }
+        }
         if (! is_dir($dir)) {
             mkdir($dir, 0775, true);
         }

package/template/laravel/src/Console/SeedCommand.php

@@ -1,124 +1,186 @@
-<?php
-
-namespace Nevela\Laravel\Console;
-
-use Illuminate\Console\Command;
-use Illuminate\Database\UniqueConstraintViolationException;
-use Illuminate\Support\Facades\DB;
-use Illuminate\Support\Str;
-use InvalidArgumentException;
-use Nevela\Laravel\Nevela;
-use Nevela\Laravel\Support\Descriptor;
-use Nevela\Laravel\Support\Fake;
-use Symfony\Component\Console\Helper\ProgressBar;
-use Throwable;
-
-final class SeedCommand extends Command
-{
-    protected $signature = 'nevela:seed
-        {name : The resource to fill, e.g. Product}
-        {--count=1000 : How many records to create}
-        {--chunk=500 : Rows per insert statement}
-        {--fresh : Delete the resource\'s existing records first}';
-
-    protected $description = 'Fill a resource with plausible records, and say how long it took';
-
-    private const MAX_COUNT = 5_000_000;
-
-    /** 400 blocks of MAX_COUNT stay under 2^31, so a unique integer column can hold the numbers. */
-    private const BLOCKS = 400;
-
-    private const ATTEMPTS = 5;
-
-    public function handle(): int
-    {
-        try {
-            $resource = Nevela::resource(Str::studly($this->argument('name')));
-        } catch (InvalidArgumentException $e) {
-            $this->components->error($e->getMessage());
-
-            return self::FAILURE;
-        }
-
-        $count = filter_var($this->option('count'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => self::MAX_COUNT]]);
-        $chunk = filter_var($this->option('chunk'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => 5000]]);
-        if ($count === false || $chunk === false) {
-            $this->components->error('--count must be between 1 and 5,000,000, and --chunk between 1 and 5,000.');
-
-            return self::FAILURE;
-        }
-
-        // SQLite allows 32,766 bound values per statement; stay well inside it on wide tables.
-        $chunk = min($chunk, max(1, intdiv(30_000, count($resource->fields) + 3)));
-        $fresh = (bool) $this->option('fresh');
-
-        $existing = $fresh ? 0 : (int) DB::table($resource->table)->count();
-        foreach ($resource->fields as $field) {
-            $capacity = Fake::capacity($field);
-            if ($capacity !== null && $existing + $count > $capacity) {
-                $room = number_format(max(0, $capacity - $existing));
-                $this->components->error("\"{$field->name}\" is unique and can only hold ".number_format($capacity)." different values, so there is room for {$room} more {$resource->pluralLabel}, not ".number_format($count).'.');
-
-                return self::FAILURE;
-            }
-        }
-
-        $started = microtime(true);
-        $removed = 0;
-        $bar = $this->output->createProgressBar($count);
-        try {
-            for ($attempt = 1; ; $attempt++) {
-                // Unique fields are numbered from a block of MAX_COUNT picked per run (a run is at
-                // most that long). Two runs only meet if they pick the same block; then the insert
-                // fails, the transaction rolls back and another block is picked.
-                $offset = $fresh && $attempt === 1 ? 0 : mt_rand(0, self::BLOCKS - 1) * self::MAX_COUNT;
-                $bar->start();
-                try {
-                    $removed = DB::transaction(fn () => $this->fill($resource, $count, $chunk, $offset, $fresh, $bar));
-                    break;
-                } catch (UniqueConstraintViolationException $e) {
-                    if ($attempt === self::ATTEMPTS) {
-                        throw $e;
-                    }
-                }
-            }
-            $bar->finish();
-            $this->newLine(2);
-        } catch (Throwable $e) {
-            $this->newLine(2);
-            $this->components->error("Seeding {$resource->pluralLabel} failed, and the table is as it was: ".Str::limit($e->getMessage(), 300));
-
-            return self::FAILURE;
-        }
-        if ($fresh) {
-            $this->components->info('Removed '.number_format($removed)." existing {$resource->pluralLabel}.");
-        }
-
-        $seconds = microtime(true) - $started;
-        $time = $seconds < 1 ? round($seconds * 1000).' ms' : number_format($seconds, 2).' s';
-        $rate = number_format($count / max($seconds, 0.001));
-        $this->components->info('Seeded '.number_format($count)." {$resource->pluralLabel} in {$time} ({$rate} rows/s).");
-        $this->components->twoColumnDetail("{$resource->pluralLabel} in the database", number_format(DB::table($resource->table)->count()));
-
-        return self::SUCCESS;
-    }
-
-    /** Runs inside the transaction: the optional delete and every insert succeed or fail together. */
-    private function fill(Descriptor $resource, int $count, int $chunk, int $offset, bool $fresh, ProgressBar $bar): int
-    {
-        $removed = $fresh ? DB::table($resource->table)->delete() : 0;
-        $now = time();
-        for ($done = 0; $done < $count; $done += $chunk) {
-            $rows = [];
-            for ($i = $done; $i < min($count, $done + $chunk); $i++) {
-                // Spread over the last 60 days, so the dashboard's "this week" and trend have something to show.
-                $created = date('Y-m-d H:i:s', $now - mt_rand(0, 60 * 86400));
-                $rows[] = ['id' => (string) Str::uuid7()] + Fake::row($resource, $offset + $i + 1) + ['created_at' => $created, 'updated_at' => $created];
-            }
-            DB::table($resource->table)->insert($rows);
-            $bar->advance(count($rows));
-        }
-
-        return $removed;
-    }
-}
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Database\UniqueConstraintViolationException;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+use InvalidArgumentException;
+use Nevela\Laravel\Media\Uploads;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Fake;
+use Symfony\Component\Console\Helper\ProgressBar;
+use Throwable;
+
+final class SeedCommand extends Command
+{
+    protected $signature = 'nevela:seed
+        {name : The resource to fill, e.g. Product}
+        {--count=1000 : How many records to create}
+        {--chunk=500 : Rows per insert statement}
+        {--fresh : Delete the resource\'s existing records first}';
+
+    protected $description = 'Fill a resource with plausible records, and say how long it took';
+
+    private const MAX_COUNT = 5_000_000;
+
+    /** 400 blocks of MAX_COUNT stay under 2^31, so a unique integer column can hold the numbers. */
+    private const BLOCKS = 400;
+
+    private const ATTEMPTS = 5;
+
+    public function handle(): int
+    {
+        try {
+            $resource = Nevela::resource(Str::studly($this->argument('name')));
+        } catch (InvalidArgumentException $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+
+        $count = filter_var($this->option('count'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => self::MAX_COUNT]]);
+        $chunk = filter_var($this->option('chunk'), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => 5000]]);
+        if ($count === false || $chunk === false) {
+            $this->components->error('--count must be between 1 and 5,000,000, and --chunk between 1 and 5,000.');
+
+            return self::FAILURE;
+        }
+
+        // SQLite allows 32,766 bound values per statement; stay well inside it on wide tables.
+        $chunk = min($chunk, max(1, intdiv(30_000, count($resource->fields) + 3)));
+        $fresh = (bool) $this->option('fresh');
+
+        $existing = $fresh ? 0 : (int) DB::table($resource->table)->count();
+        foreach ($resource->fields as $field) {
+            $capacity = Fake::capacity($field);
+            if ($capacity !== null && $existing + $count > $capacity) {
+                $room = number_format(max(0, $capacity - $existing));
+                $this->components->error("\"{$field->name}\" is unique and can only hold ".number_format($capacity)." different values, so there is room for {$room} more {$resource->pluralLabel}, not ".number_format($count).'.');
+
+                return self::FAILURE;
+            }
+        }
+
+        // --fresh deletes first, and a record others are required to belong to can't be deleted.
+        // Said here, before any placeholder pictures are made for a run that can't happen.
+        if ($fresh) {
+            foreach (Nevela::all() as $other) {
+                foreach ($other->fields as $field) {
+                    if ($field->kind === 'belongsTo' && $field->target === $resource->name && $field->required && $other->name !== $resource->name
+                        && ($children = (int) DB::table($other->table)->count()) > 0) {
+                        $this->components->error(number_format($children)." {$other->pluralLabel} belong to the {$resource->pluralLabel} that --fresh would delete. Remove them first, or seed without --fresh.");
+
+                        return self::FAILURE;
+                    }
+                }
+            }
+        }
+
+        $started = microtime(true);
+        try {
+            $pools = $this->pools($resource);
+        } catch (InvalidArgumentException $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+        $removed = 0;
+        $bar = $this->output->createProgressBar($count);
+        try {
+            for ($attempt = 1; ; $attempt++) {
+                // Unique fields are numbered from a block of MAX_COUNT picked per run (a run is at
+                // most that long). Two runs only meet if they pick the same block; then the insert
+                // fails, the transaction rolls back and another block is picked.
+                $offset = $fresh && $attempt === 1 ? 0 : mt_rand(0, self::BLOCKS - 1) * self::MAX_COUNT;
+                $bar->start();
+                try {
+                    $removed = DB::transaction(fn () => $this->fill($resource, $count, $chunk, $offset, $fresh, $bar, $pools));
+                    break;
+                } catch (UniqueConstraintViolationException $e) {
+                    if ($attempt === self::ATTEMPTS) {
+                        throw $e;
+                    }
+                }
+            }
+            $bar->finish();
+            $this->newLine(2);
+        } catch (Throwable $e) {
+            $this->newLine(2);
+            $this->components->error("Seeding {$resource->pluralLabel} failed, and the table is as it was: ".Str::limit($e->getMessage(), 300));
+
+            return self::FAILURE;
+        }
+        if ($fresh) {
+            $this->components->info('Removed '.number_format($removed)." existing {$resource->pluralLabel}.");
+        }
+
+        $seconds = microtime(true) - $started;
+        $time = $seconds < 1 ? round($seconds * 1000).' ms' : number_format($seconds, 2).' s';
+        $rate = number_format($count / max($seconds, 0.001));
+        $this->components->info('Seeded '.number_format($count)." {$resource->pluralLabel} in {$time} ({$rate} rows/s).");
+        $this->components->twoColumnDetail("{$resource->pluralLabel} in the database", number_format(DB::table($resource->table)->count()));
+
+        return self::SUCCESS;
+    }
+
+    /**
+     * What a relation or an image field can be filled with: the records that exist to point
+     * at, and a handful of pictures made for the purpose.
+     *
+     * @return array<string, list<string>>
+     *
+     * @throws InvalidArgumentException when a required field has nothing to draw from
+     */
+    private function pools(Descriptor $resource): array
+    {
+        $pools = [];
+        foreach ($resource->fields as $field) {
+            if ($field->kind === 'belongsTo') {
+                $target = $field->target === $resource->name ? $resource : Nevela::resource((string) $field->target);
+                $ids = DB::table($target->table)->inRandomOrder()->limit(1000)->pluck('id')->map(fn ($id) => (string) $id)->all();
+                if ($field->unique) {
+                    throw new InvalidArgumentException("\"{$field->name}\" is unique, so each {$target->label} can be used once. The seeder doesn't fill one-to-one relations; add those records yourself.");
+                }
+                if ($ids === [] && $field->required && $target->name !== $resource->name) {
+                    throw new InvalidArgumentException("Every {$resource->label} needs a {$target->label}, and there are none yet. Seed them first: php artisan nevela:seed {$target->name}");
+                }
+                $pools[$field->name] = $ids;
+            } elseif ($field->kind === 'file') {
+                $pools[$field->name] = $field->isImage() ? Uploads::placeholders($resource, $field) : [];
+                if ($pools[$field->name] === [] && $field->required) {
+                    throw new InvalidArgumentException($field->isImage()
+                        ? "\"{$field->name}\" is a required image, and PHP's GD extension isn't installed to make placeholder pictures with."
+                        : "\"{$field->name}\" is a required file, which the seeder can't make up. Make it optional ({$field->name}:file(…)?) or add records yourself.");
+                }
+            }
+        }
+
+        return $pools;
+    }
+
+    /**
+     * Runs inside the transaction: the optional delete and every insert succeed or fail together.
+     *
+     * @param  array<string, list<string>>  $pools
+     */
+    private function fill(Descriptor $resource, int $count, int $chunk, int $offset, bool $fresh, ProgressBar $bar, array $pools = []): int
+    {
+        $removed = $fresh ? DB::table($resource->table)->delete() : 0;
+        $now = time();
+        for ($done = 0; $done < $count; $done += $chunk) {
+            $rows = [];
+            for ($i = $done; $i < min($count, $done + $chunk); $i++) {
+                // Spread over the last 60 days, so the dashboard's "this week" and trend have something to show.
+                $created = date('Y-m-d H:i:s', $now - mt_rand(0, 60 * 86400));
+                $rows[] = ['id' => (string) Str::uuid7()] + Fake::row($resource, $offset + $i + 1, $pools) + ['created_at' => $created, 'updated_at' => $created];
+            }
+            DB::table($resource->table)->insert($rows);
+            $bar->advance(count($rows));
+        }
+
+        return $removed;
+    }
+}