create-nevela 0.7.1 → 0.9.1

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

@@ -7,6 +7,7 @@ use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Schema;
 use Illuminate\Support\Str;
 use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Support\Key;
 
 /**
  * Accounts that were closed, and the emails that may not have a new one.
@@ -207,7 +208,7 @@ final class ClosedAccounts
     /** Let an email whose account was removed for good be used again. False when there is no such entry. */
     public static function allow(string $id): bool
     {
-        return DB::table(self::BLOCKED)->where('id', $id)->whereNull('user_id')->delete() > 0;
+        return Key::isUuid($id) && DB::table(self::BLOCKED)->where('id', $id)->whereNull('user_id')->delete() > 0;
     }
 
     /** Remember an email by its fingerprint: for a closed account, or with no account left. */

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

@@ -29,6 +29,14 @@ final class Permissions
     /** @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 permissions that are a resource's own actions, such as "internship_applications.accept".
+     * They are the only ones outside the four, and are only ever given by name.
+     *
+     * @var array<string, true>
+     */
+    private static array $own = [];
+
     /**
      * 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.
@@ -41,6 +49,7 @@ final class Permissions
             return self::$catalog;
         }
 
+        self::$own = [];
         $taken = ['users' => true, 'roles' => true];
         $modules = [[
             'key' => 'access',
@@ -64,7 +73,14 @@ final class Permissions
             $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];
+            $feature = ['key' => $descriptor->table, 'name' => $descriptor->pluralLabel, 'actions' => self::ACTIONS];
+            // The resource's own actions, after the four: one permission each, with the name its button has.
+            foreach ($descriptor->actions as $action) {
+                $feature['actions'][] = $action->key();
+                $feature['labels'][$action->key()] = $action->label;
+                self::$own["{$descriptor->table}.{$action->key()}"] = true;
+            }
+            $groups[$heading]['features'][] = $feature;
         }
         if ($groups !== []) {
             $modules[] = ['key' => 'resources', 'name' => 'Resources', 'groups' => array_values($groups)];
@@ -92,6 +108,7 @@ final class Permissions
     public static function forget(): void
     {
         self::$catalog = null;
+        self::$own = [];
     }
 
     /**
@@ -119,7 +136,16 @@ final class Permissions
     /** 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);
+        if (preg_match('/^[a-z][a-z0-9_]*\.(create|view|edit|delete)$/', $ability)) {
+            return true;
+        }
+        // Or one of a resource's own actions. Anything else with a dot in it is the app's to define.
+        if (! str_contains($ability, '.')) {
+            return false;
+        }
+        self::catalog();
+
+        return isset(self::$own[$ability]);
     }
 
     /**
@@ -144,6 +170,11 @@ final class Permissions
      * 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".
+     *
+     * In the second half, "*" is the four things every feature has: create, view, edit and
+     * delete. A resource's own action, such as accepting an application, is covered only
+     * by its own name or by "*" alone. Someone given "everything to do with the records"
+     * has not thereby been given the button that sends a letter.
      */
     public static function matches(string $pattern, string $key): bool
     {
@@ -165,7 +196,7 @@ final class Permissions
             return false;
         }
 
-        return $action === '*' || $action === $k[1];
+        return $action === '*' ? in_array($k[1], self::ACTIONS, true) : $action === $k[1];
     }
 
     /**
@@ -236,10 +267,10 @@ final class Permissions
         if ($grant === '*') {
             return true;
         }
-        if (! preg_match('/^(\*|@?[a-z][a-z0-9_]*)\.(\*|create|view|edit|delete)$/', $grant)) {
+        if (! preg_match('/^(\*|@?[a-z][a-z0-9_]*)\.(\*|[a-z][a-z0-9_]*)$/', $grant, $m)) {
             return false;
         }
-        if (str_starts_with($grant, '@')) {
+        if (str_starts_with($grant, '@') && in_array($m[2], ['*', ...self::ACTIONS], true)) {
             return in_array(substr(explode('.', $grant)[0], 1), ['access', 'resources', 'app'], true);
         }
 

package/template/laravel/src/Concerns/Confirmable.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Nevela\Laravel\Concerns;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * A model whose records hold an address that has to be proved: a list people join.
+ *
+ * A record made through the public form starts unconfirmed (`confirmed_at` is null) and
+ * is confirmed when the link emailed to its address is followed. Until then it is left
+ * out of counts and exports, and after two days it is removed. Whatever goes to
+ * "everyone on the list" goes to the confirmed:
+ *
+ *     Subscriber::confirmed()->each(fn ($subscriber) => …);
+ *
+ * A record made any other way (in the dashboard, by a seeder, by an import) is confirmed
+ * as it is made: someone signed in put it there, and there is nobody to ask.
+ *
+ * Generated models use it when their descriptor's public create has "confirm".
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait Confirmable
+{
+    /** Whether this model's table has the column. Only "yes" is remembered: it can arrive later in a process. */
+    private static bool $hasConfirmation = false;
+
+    public static function confirms(): bool
+    {
+        if (static::$hasConfirmation) {
+            return true;
+        }
+        $model = new static;
+
+        return static::$hasConfirmation = Schema::connection($model->getConnectionName())->hasColumn($model->getTable(), 'confirmed_at');
+    }
+
+    /** Ask the database again next time. For a test that adds the column within one process. */
+    public static function forgetConfirmation(): void
+    {
+        static::$hasConfirmation = false;
+    }
+
+    public static function bootConfirmable(): void
+    {
+        static::creating(function (self $model) {
+            // The public form says "not yet" by setting the column to null itself. Anything
+            // else that makes a record says nothing, and is taken at its word.
+            if (! array_key_exists('confirmed_at', $model->getAttributes()) && static::confirms()) {
+                $model->setAttribute('confirmed_at', $model->freshTimestamp());
+            }
+        });
+    }
+
+    public function initializeConfirmable(): void
+    {
+        $this->mergeCasts(['confirmed_at' => 'datetime']);
+    }
+
+    /** Whether this record's address has been proved. */
+    public function isConfirmed(): bool
+    {
+        return $this->getAttribute('confirmed_at') !== null;
+    }
+
+    /** The records whose address has been proved: the ones to count, export and write to. */
+    public function scopeConfirmed(Builder $query): void
+    {
+        if (static::confirms()) {
+            $query->whereNotNull($this->qualifyColumn('confirmed_at'));
+        }
+    }
+
+    /** The ones still waiting for their link to be followed. */
+    public function scopeUnconfirmed(Builder $query): void
+    {
+        static::confirms() ? $query->whereNull($this->qualifyColumn('confirmed_at')) : $query->whereRaw('1 = 0');
+    }
+}

package/template/laravel/src/Concerns/Trashable.php

@@ -4,6 +4,9 @@ namespace Nevela\Laravel\Concerns;
 
 use Illuminate\Database\Eloquent\SoftDeletes;
 use Illuminate\Support\Facades\Schema;
+use InvalidArgumentException;
+use Nevela\Laravel\Media\Uploads;
+use Nevela\Laravel\Nevela;
 use Nevela\Laravel\Trash\TrashedScope;
 
 /**
@@ -59,5 +62,25 @@ trait Trashable
                 $model->forceDeleting = true;
             }
         });
+
+        // A private file goes when its record goes for good. In the trash the record still
+        // exists, and so does its file, unreachable, for the day it is restored.
+        static::deleted(function (self $model) {
+            if ($model->exists) {
+                return;
+            }
+            try {
+                $resource = Nevela::resource(class_basename($model));
+            } catch (InvalidArgumentException) {
+                return; // a model that uses the trash without being a resource
+            }
+            foreach ($resource->fields as $field) {
+                $key = $field->kind === 'file' && $field->private ? $model->getAttribute($field->column()) : null;
+                // Not while another record of the table still points at the same file.
+                if (is_string($key) && $key !== '' && ! $model->newQueryWithoutScopes()->where($field->column(), $key)->exists()) {
+                    Uploads::discard($key);
+                }
+            }
+        });
     }
 }

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

@@ -0,0 +1,139 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use InvalidArgumentException;
+use Nevela\Laravel\Generator\GeneratedFile;
+use Nevela\Laravel\Generator\ResourceGenerator;
+use Nevela\Laravel\Generator\Writer;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Adoption;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Naming;
+
+final class AdoptCommand extends Command
+{
+    protected $signature = 'nevela:adopt
+        {table : The table to make a resource of, e.g. posts}
+        {--name= : The resource\'s name, when it isn\'t the table\'s own (posts is Post)}
+        {--icon= : Lucide icon name for the dashboard, e.g. newspaper}
+        {--group= : Sidebar group in the dashboard}
+        {--yes : Write it without asking}
+        {--force : Replace the descriptor this table already has}';
+
+    protected $description = 'Make a resource of a table you already have: its descriptor is read from the table, which is left as it is';
+
+    public function handle(): int
+    {
+        $table = (string) $this->argument('table');
+        if (str_starts_with($table, 'nevela_') || $table === 'migrations') {
+            $this->components->error("{$table} is a table Nevela or Laravel keeps for itself.");
+
+            return self::FAILURE;
+        }
+
+        Nevela::forget();
+        try {
+            $all = Nevela::all();
+            // The descriptor this table has already, if it is being adopted again.
+            $others = array_values(array_filter($all, fn (Descriptor $d) => $d->table !== $table));
+            $existing = array_values(array_filter($all, fn (Descriptor $d) => $d->table === $table))[0] ?? null;
+            if ($existing !== null && ! $this->option('force')) {
+                $this->components->error("{$table} is a resource already. Edit its descriptor and run: php artisan nevela:generate. To read it from the table again, add --force.");
+
+                return self::FAILURE;
+            }
+            $name = $this->option('name');
+            // Read again, it stays the resource it is. Under another name the first descriptor
+            // would still be there, and the table would be two resources.
+            if ($existing !== null && $name !== null && Naming::pascal($name) !== $existing->name) {
+                $this->components->error("{$table} is the {$existing->name} resource, and --force reads it again under that name. To call it something else, remove nevela/resources/".Naming::kebab($existing->name).'.json and the code generated for it, then adopt the table again.');
+
+                return self::FAILURE;
+            }
+            $adoption = Adoption::of($table, $others, $existing?->name ?? $name, $this->option('icon') ?? $existing?->icon, $this->option('group') ?? $existing?->group);
+        } catch (InvalidArgumentException $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+        $descriptor = $adoption->descriptor;
+
+        $dir = rtrim(config('nevela.descriptors_path'), '/\\');
+        $path = $dir.DIRECTORY_SEPARATOR.Naming::kebab($descriptor->name).'.json';
+        foreach ($others as $other) {
+            if ($other->name === $descriptor->name) {
+                $this->components->error("There is a {$descriptor->name} already, on the {$other->table} table. Give this one another name: --name=…");
+
+                return self::FAILURE;
+            }
+        }
+        if ($taken = $this->ownFiles($descriptor, [...$others, $descriptor])) {
+            $this->components->error("The name {$descriptor->name} is taken by code of your own, which Nevela won't write over:");
+            $this->components->bulletList($taken);
+            $this->line("  Adopt the table under another name (<fg=cyan>--name=…</>), or move those files aside first.");
+
+            return self::FAILURE;
+        }
+
+        $this->components->info("{$table} as {$descriptor->name}, with ".($descriptor->idType === 'int' ? 'integer' : 'UUID').' ids');
+        foreach ($adoption->fields as $column => $field) {
+            $this->components->twoColumnDetail($column, "{$field->name}:".Adoption::spec($field));
+        }
+        foreach ($adoption->left as $left) {
+            $this->components->twoColumnDetail($left['column'], "<fg=gray>left alone: {$left['why']}</>");
+        }
+        if ($adoption->notes !== []) {
+            $this->newLine();
+            $this->components->bulletList($adoption->notes);
+        }
+
+        if (! $this->option('yes') && ! $this->components->confirm("Make {$descriptor->name} a resource? The table is not changed", true)) {
+            $this->components->info('Nothing was written.');
+
+            return self::SUCCESS;
+        }
+
+        if (! is_dir($dir)) {
+            mkdir($dir, 0775, true);
+        }
+        file_put_contents($path, $descriptor->toJson());
+        $this->components->info("Described {$descriptor->name} in ".str_replace(base_path().DIRECTORY_SEPARATOR, '', $path));
+
+        Nevela::forget();
+        $status = GenerateCommand::generate($this, [$descriptor], Nevela::all(), false);
+
+        $this->newLine();
+        $this->line('  Next: <fg=cyan>php artisan migrate</> gives the table a trash (a deleted_at column), then tighten <fg=cyan>app/Policies/'.$descriptor->name.'Policy.php</>.');
+        $this->line('  Every column came in as the plainest type that holds it. Where one is an email, a slug or a choice, say so in the descriptor and run <fg=cyan>php artisan nevela:generate</>.');
+
+        return $status;
+    }
+
+    /**
+     * Files this resource would be written to that are there already and aren't Nevela's:
+     * a model of the same name, most often. Their generated block has nowhere to go, and a
+     * resource whose model lacks it only half works.
+     *
+     * @param  list<Descriptor>  $all
+     * @return list<string>
+     */
+    private function ownFiles(Descriptor $descriptor, array $all): array
+    {
+        $roots = [GeneratedFile::TARGET_API => base_path()];
+        if (($web = config('nevela.web_path')) && is_dir($web)) {
+            $roots[GeneratedFile::TARGET_WEB] = $web;
+        }
+        $taken = [];
+        foreach ((new ResourceGenerator)->forResource($descriptor, null, $all) as $file) {
+            $root = $roots[$file->target] ?? null;
+            $absolute = $root === null ? null : rtrim($root, '/\\').DIRECTORY_SEPARATOR.$file->path;
+            if ($file->mode === GeneratedFile::MODE_BLOCK && $absolute !== null && is_file($absolute) && Writer::block((string) file_get_contents($absolute)) === null) {
+                $taken[] = $file->path;
+            }
+        }
+
+        return $taken;
+    }
+}

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

@@ -0,0 +1,254 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Schema;
+use InvalidArgumentException;
+use Nevela\Laravel\Generator\BlogPages;
+use Nevela\Laravel\Generator\GeneratedFile;
+use Nevela\Laravel\Generator\Writer;
+use Nevela\Laravel\Media\Uploads;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Naming;
+
+/**
+ * A blog for the site: posts written in the dashboard, and /blog to read them at.
+ *
+ *   php artisan nevela:blog                          a Post resource, and the pages
+ *   php artisan nevela:blog --resource=Article …     the pages only, reading a resource the app has
+ *
+ * Everything a blog is made of is already a resource's to have: rich text, an image, a
+ * slug, a date it is published on, and public reading. This puts them together, and
+ * writes the pages that show the result.
+ */
+final class BlogCommand extends Command
+{
+    /** The resource this makes when the app has none to read. */
+    public const RESOURCE = 'Post';
+
+    public const PATH = '/blog';
+
+    protected $signature = 'nevela:blog
+        {--resource= : Read the posts from a resource you already have, and write only the pages}
+        {--title= : That resource\'s field for a post\'s title. Default: title}
+        {--body= : Its field for the post itself. Default: body}
+        {--excerpt= : Its field for a sentence or two about the post, if it has one}
+        {--image= : Its field for a picture, if it has one}
+        {--published= : Its field for when a post was published. Default: the one the resource is published by}
+        {--sample : Add three posts to start with. For development: refused in production}
+        {--no-migrate : Don\'t create the posts table yet}';
+
+    protected $description = 'Give the site a blog: a Post resource to write in, and /blog to read it at';
+
+    public function handle(): int
+    {
+        Nevela::forget();
+        try {
+            $all = Nevela::all();
+            $given = $this->option('resource');
+            [$descriptor, $fields, $created] = $given === null
+                ? $this->ours($all)
+                : [...$this->theirs((string) $given, $all), false];
+        } catch (InvalidArgumentException $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+
+        $dir = rtrim(config('nevela.descriptors_path'), '/\\');
+        if (! is_dir($dir)) {
+            mkdir($dir, 0775, true);
+        }
+        // The descriptor says where the blog is, so the site's header can link to it.
+        file_put_contents($dir.DIRECTORY_SEPARATOR.Naming::kebab($descriptor->name).'.json', $descriptor->toJson());
+        Nevela::forget();
+        if (GenerateCommand::generate($this, [$descriptor], Nevela::all(), false) !== self::SUCCESS) {
+            return self::FAILURE;
+        }
+
+        $web = config('nevela.web_path');
+        if (! $web || ! is_dir($web)) {
+            $this->components->warn('There is no web app at nevela.web_path, so the pages were not written. Run this again when there is.');
+        } else {
+            foreach ((new Writer([GeneratedFile::TARGET_WEB => $web]))->write(BlogPages::files($descriptor, $fields)) as $row) {
+                $path = str_replace('\\', '/', substr($row['path'], strlen(rtrim($web, '/\\')) + 1));
+                $this->components->twoColumnDetail("../web/{$path}", $row['status'] === 'created' ? '<fg=green>created</>' : '<fg=gray>exists (yours)</>');
+            }
+        }
+
+        $status = self::SUCCESS;
+        if ($created && ! $this->option('no-migrate')) {
+            $status = $this->call('migrate', ['--force' => true]);
+        }
+        if ($status === self::SUCCESS && $this->option('sample')) {
+            $status = $this->sample($descriptor);
+        }
+
+        $this->newLine();
+        $this->line('  The blog is at <fg=cyan>'.self::PATH.'</>, and '.$descriptor->pluralLabel.' is in the dashboard. A post is on the site once it has been published.');
+        if (! $created) {
+            $this->line('  Which records are public is the scope on <fg=cyan>app/Models/'.$descriptor->name.'.php</> (scopePublicQuery). The pages and <fg=cyan>lib/blog.ts</> are yours to change.');
+        }
+
+        return $status;
+    }
+
+    /**
+     * The Post resource, made here: what a post is, that it is published by a date, and
+     * that anyone may read a published one by its slug.
+     *
+     * @param  list<Descriptor>  $all
+     * @return array{Descriptor, array<string, string|null>, bool}
+     */
+    private function ours(array $all): array
+    {
+        $fields = ['title' => 'title', 'body' => 'body', 'excerpt' => 'excerpt', 'image' => 'image', 'published' => 'publishedAt'];
+        foreach ($all as $existing) {
+            if ($existing->name === self::RESOURCE || $existing->table === 'posts') {
+                // Run again on an app that has it: the pages are written if they aren't there, and nothing else changes.
+                if ($existing->blog !== null) {
+                    return [$existing, array_map(fn (?string $field) => $field !== null && isset($existing->fields[$field]) ? $field : null, $fields), false];
+                }
+                throw new InvalidArgumentException("There is a {$existing->name} resource already. To have the blog read it: php artisan nevela:blog --resource={$existing->name}");
+            }
+        }
+        if ($this->tableExists('posts')) {
+            throw new InvalidArgumentException('There is a posts table already, which is not a resource. Adopt it (php artisan nevela:adopt posts), then: php artisan nevela:blog --resource=Post');
+        }
+
+        $descriptor = Descriptor::fromArray([
+            'name' => self::RESOURCE,
+            'icon' => 'book',
+            'publish' => 'publishedAt',
+            'blog' => self::PATH,
+            'fields' => [
+                'title' => ['kind' => 'string'],
+                'slug' => ['kind' => 'string', 'format' => 'slug', 'unique' => true, 'from' => 'title'],
+                'excerpt' => ['kind' => 'string', 'maxLength' => 500, 'required' => false],
+                'body' => ['kind' => 'text', 'format' => 'rich'],
+                'image' => ['kind' => 'file', 'accept' => ['image'], 'profile' => 'cover', 'required' => false],
+                'publishedAt' => ['kind' => 'datetime', 'required' => false],
+            ],
+            'public' => ['read' => ['by' => 'slug', 'fields' => ['title', 'slug', 'excerpt', 'body', 'image', 'publishedAt']]],
+        ]);
+
+        return [$descriptor, $fields, true];
+    }
+
+    /**
+     * A resource the app already has, read as posts. Nothing about it is changed but the
+     * note of where its blog is; what it lacks for a blog is said, and nothing is written.
+     *
+     * @param  list<Descriptor>  $all
+     * @return array{Descriptor, array<string, string|null>}
+     *
+     * @throws InvalidArgumentException
+     */
+    private function theirs(string $name, array $all): array
+    {
+        $descriptor = null;
+        foreach ($all as $candidate) {
+            if (strcasecmp($candidate->name, $name) === 0) {
+                $descriptor = $candidate;
+            }
+        }
+        if ($descriptor === null) {
+            throw new InvalidArgumentException("There is no resource called {$name}.");
+        }
+        $public = $descriptor->public;
+        if ($public?->read === null) {
+            throw new InvalidArgumentException("{$descriptor->name} can't be read publicly, and a blog is public. Add to its descriptor: \"public\": { \"read\": { \"by\": \"slug\", \"fields\": [ … ] } }");
+        }
+        if ($public->by === null) {
+            throw new InvalidArgumentException("{$descriptor->name}'s public section doesn't say which unique field a record is fetched by, and a post's address is made from one. Add \"by\": \"slug\" to its \"read\".");
+        }
+
+        $fields = [];
+        foreach (['title' => 'title', 'body' => 'body', 'excerpt' => null, 'image' => null, 'published' => $descriptor->publish] as $part => $default) {
+            $asked = $this->option($part);
+            // A column's name is understood as well as the field's: published_at, publishedAt.
+            $field = $asked === null ? $default : Naming::camel((string) $asked);
+            if ($field === null) {
+                $fields[$part] = null;
+
+                continue;
+            }
+            if (! isset($descriptor->fields[$field])) {
+                throw new InvalidArgumentException("{$descriptor->name} has no field called {$field}. Name the one that is a post's {$part}: --{$part}=…");
+            }
+            if (! in_array($field, $public->read, true)) {
+                throw new InvalidArgumentException("\"{$field}\" is not among the fields anyone may read of {$descriptor->name}, so the blog couldn't show it. Add it to \"public.read.fields\" in its descriptor.");
+            }
+            $fields[$part] = $field;
+        }
+
+        $data = $descriptor->toArray();
+        $data['blog'] = self::PATH;
+
+        return [Descriptor::fromArray($data), $fields];
+    }
+
+    /**
+     * Three posts, so /blog has something on it the first time it is opened. Like the
+     * sample users: for looking around a new app, and never for a live one.
+     */
+    private function sample(Descriptor $descriptor): int
+    {
+        if (app()->environment('production')) {
+            $this->components->error('Sample posts are for development. This app is in production, so none were made.');
+
+            return self::FAILURE;
+        }
+        $model = "App\\Models\\{$descriptor->name}";
+        if ($descriptor->name !== self::RESOURCE || ! class_exists($model) || ! $this->tableExists($descriptor->table)) {
+            $this->components->warn('Sample posts are for the Post resource this command makes, once its table is there.');
+
+            return self::SUCCESS;
+        }
+        if ($model::query()->exists()) {
+            return self::SUCCESS; // it has posts already; these would only be in the way
+        }
+
+        // A picture each, where pictures can be made here.
+        $pictures = Uploads::placeholders($descriptor, $descriptor->fields['image'], 3);
+        foreach (self::POSTS as $index => $post) {
+            $model::create($post + ['image' => $pictures[$index] ?? null, 'published_at' => now()->subDays(1 + $index * 3)]);
+        }
+        $this->components->info('Added three sample posts. Edit or delete them under Posts in the dashboard.');
+
+        return self::SUCCESS;
+    }
+
+    private function tableExists(string $table): bool
+    {
+        try {
+            return Schema::hasTable($table);
+        } catch (\Throwable) {
+            return false; // no database to ask yet
+        }
+    }
+
+    /** @var list<array{title: string, slug: string, excerpt: string, body: string}> */
+    private const POSTS = [
+        [
+            'title' => 'Welcome to your blog',
+            'slug' => 'welcome-to-your-blog',
+            'excerpt' => 'This post came with the app. It is here so the blog has something on it the first time you open it.',
+            'body' => '<p>This post came with the app. It is here so the blog has something on it the first time you open it, and you can delete it whenever you like.</p><h2>Where posts are written</h2><p>Sign in and open <strong>Posts</strong> in the dashboard. A post has a title, an excerpt for the list, a picture and a body with headings, lists, links and quotes.</p><h2>Where they are read</h2><p>At <a href="/blog">/blog</a>, newest first, and each at an address of its own made from its title.</p>',
+        ],
+        [
+            'title' => 'Drafts, publishing and scheduling',
+            'slug' => 'drafts-publishing-and-scheduling',
+            'excerpt' => 'A post is not on the site until it is published. Until then it is a draft, and only people who sign in can see it.',
+            'body' => '<p>A post is not on the site until it is published. Until then it is a draft, and only people who sign in can see it.</p><ul><li><strong>Publish</strong> puts it on the site at once.</li><li><strong>Unpublish</strong> takes it off again and keeps it as a draft.</li><li>Give it a date and time still to come and it is <strong>scheduled</strong>: it appears by itself when that time arrives.</li></ul><p>The list in the dashboard says which of the three each post is, and can be filtered by it.</p>',
+        ],
+        [
+            'title' => 'Making the blog yours',
+            'slug' => 'making-the-blog-yours',
+            'excerpt' => 'The pages that show the blog were written once, into your own app, and are yours to change.',
+            'body' => '<p>The pages that show the blog were written once, into your own app, and are yours to change.</p><h3>What to open</h3><ol><li><strong>lib/blog.ts</strong> for the blog\'s title, its description and how many posts are on a page.</li><li><strong>app/blog</strong> for the list and for a post\'s own page.</li></ol><blockquote><p>There is an RSS feed at /blog/feed.xml, and every published post is in the sitemap.</p></blockquote>',
+        ],
+    ];
+}

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

@@ -40,6 +40,13 @@ final class DevCommand extends Command
             $web = Process::fromShellCommandline(self::packageManager($webPath).' run dev', $webPath, ['NEVELA_API_URL' => "{$url}/api"], null, null);
         }
 
+        // Mail a public form causes is queued, and a queue with nobody working it sends
+        // nothing: a confirmation link would never arrive. So the queue is worked here too,
+        // unless the app runs jobs as they are made.
+        $queue = in_array(config('queue.default'), ['sync', 'null', null], true)
+            ? null
+            : new Process([$php, 'artisan', 'queue:listen', '--tries=1', '--sleep=2'], base_path(), null, null, null);
+
         $this->components->info('Starting '.($web ? 'the API and the dashboard' : 'the API').'. Press Ctrl+C to stop.');
         $this->components->twoColumnDetail('API', $url);
         if ($web) {
@@ -49,6 +56,7 @@ final class DevCommand extends Command
 
         $api->start($this->printer('api', 35));
         $web?->start($this->printer('web', 36));
+        $queue?->start($this->printer('queue', 33));
 
         try {
             while ($api->isRunning() && ($web === null || $web->isRunning())) {
@@ -56,6 +64,7 @@ final class DevCommand extends Command
             }
         } finally {
             // Whichever stopped, or Ctrl+C: don't leave the other one running behind.
+            $queue?->stop(3);
             $web?->stop(3);
             $api->stop(3);
         }