create-nevela 0.7.1 → 0.8.0

package/index.mjs

@@ -75,6 +75,7 @@ const HELP = `  Create a new Nevela app: a Laravel API and a Next.js dashboard.
     nevela dev                 Run the API and the dashboard
     nevela status              Check versions, migrations, users and the dashboard
     nevela resource <Name> --fields="…" [--seed]
+    nevela adopt <table>       Make a resource of a table you already have
     nevela seed | user | generate | migrate | trash | artisan <command>
 
   ${bold('Options')}

package/package.json

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

package/project.mjs

@@ -11,7 +11,7 @@ import { isNewer, satisfiesCaret } from './packagist.mjs';
 import { spawnCommand } from './shell.mjs';
 
 /** What `nevela <name>` runs: these go to `php artisan nevela:<name>`. */
-const NEVELA = ['upgrade', 'dev', 'status', 'version', 'resource', 'generate', 'seed', 'user', 'trash'];
+const NEVELA = ['upgrade', 'dev', 'status', 'version', 'resource', 'adopt', 'generate', 'seed', 'user', 'trash'];
 /** These go to the artisan command of the same name. */
 const ARTISAN = ['migrate', 'tinker', 'test', 'serve'];
 

package/template/laravel/config/nevela.php

@@ -131,6 +131,19 @@ return [
         'days' => 30,
     ],
 
+    /*
+    | Rich text fields (body:richtext). Whatever is sent is parsed and written out again
+    | with only these tags and attributes: nothing the editor, a script or a visitor sends
+    | is trusted. A tag that isn't listed goes and its words stay. The list matches the
+    | dashboard editor's toolbar; add to it only what you would let a stranger put on a page.
+    | A link may use these schemes, or none (/about).
+    */
+    'rich_text' => [
+        'tags' => ['p', 'br', 'strong', 'em', 's', 'a', 'h2', 'h3', 'ul', 'ol', 'li', 'blockquote'],
+        'attributes' => ['a' => ['href']],
+        'schemes' => ['http', 'https', 'mailto'],
+    ],
+
     /*
     | The most rows POST /{slug}/_bulk creates in one request (the dashboard's "Add several"
     | grid). They are saved in one transaction, so this is also how long one can run.
@@ -142,14 +155,23 @@ return [
     |
     | 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.
+    | are unguessable, but anyone who has one can fetch the file. If a CDN or your web
+    | server serves the disk, put its address in NEVELA_UPLOADS_URL and the API's links
+    | point there.
+    |
+    | A document that must stay private goes in a private file field ("private": true in
+    | the descriptor, or cv:file(pdf|private)). It is kept on private_disk, which must not
+    | be one the web server serves, and is handed out by
+    | GET {prefix}/_nevela/private/{slug}/{id}/{field} to someone signed in who may view
+    | that record. Its key opens nothing.
     */
     'uploads' => [
         'disk' => env('NEVELA_UPLOADS_DISK', 'public'),
         'url' => env('NEVELA_UPLOADS_URL'),
 
+        /* Where private files are kept. Never served: not "public", and not a bucket anyone can read. */
+        'private_disk' => env('NEVELA_PRIVATE_DISK', 'local'),
+
         /* Where untouched originals are kept, so an image can be optimised again later. Never served. */
         'originals_disk' => env('NEVELA_ORIGINALS_DISK', 'local'),
 

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/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/GenerateCommand.php

@@ -28,10 +28,11 @@ final class GenerateCommand extends Command
      * @param  list<string>  $createMigrations  The contents of the table's own migration(s); none for a resource that is new
      * @param  bool  $written  Whether an add_trash_to_… migration exists for the table already
      * @param  bool  $columnExists  Whether the table has deleted_at in the database now
+     * @param  bool  $adopted  Whether the table was there before Nevela: then there may be no migration of that name to read
      */
-    public static function needsTrashMigration(array $createMigrations, bool $written, bool $columnExists): bool
+    public static function needsTrashMigration(array $createMigrations, bool $written, bool $columnExists, bool $adopted = false): bool
     {
-        if ($createMigrations === []) {
+        if ($createMigrations === [] && ! $adopted) {
             return false;
         }
         foreach ($createMigrations as $contents) {
@@ -127,11 +128,12 @@ final class GenerateCommand extends Command
             // resource's own migration, written by the line above, already has the column.
             $made = array_map(fn (string $file) => (string) file_get_contents($file), glob(database_path("migrations/*_create_{$descriptor->table}_table.php")) ?: []);
             $written = (glob(database_path("migrations/*_add_trash_to_{$descriptor->table}_table.php")) ?: []) !== [];
-            if (self::needsTrashMigration($made, $written, self::hasTrashColumn($descriptor->table))) {
+            if (self::needsTrashMigration($made, $written, self::hasTrashColumn($descriptor->table), $descriptor->adopted)) {
                 $files[] = $generator->trashMigrationFile($descriptor);
             }
         }
         $files[] = $generator->routes($all);
+        $files[] = $generator->publicRoutes($all);
         $files[] = $generator->registry($all);
         $files[] = $generator->authConfig((array) config('nevela.auth', []));
 
@@ -168,6 +170,14 @@ final class GenerateCommand extends Command
         if ($edited) {
             $command->components->warn("{$edited} file(s) skipped because you edited their generated block. Move your changes outside it, or rerun with --force.");
         }
+        // A model written before its resource was made public has no scope saying which
+        // records are, and without one none are. Said, so an empty public list isn't a puzzle.
+        foreach ($queue as $descriptor) {
+            $model = base_path("app/Models/{$descriptor->name}.php");
+            if ($descriptor->public?->read !== null && is_file($model) && ! str_contains((string) file_get_contents($model), 'scopePublicQuery')) {
+                $command->components->warn("{$descriptor->name} can be read publicly, but its model doesn't say which records may be, so none are. Add to app/Models/{$descriptor->name}.php: public function scopePublicQuery(\\Illuminate\\Database\\Eloquent\\Builder \$query): void { … }");
+            }
+        }
 
         return self::SUCCESS;
     }

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

@@ -15,6 +15,7 @@ final class MakeResourceCommand extends Command
         {--fields= : "name:string, sku:string!, price:money, status:enum(draft|live), notes:text?"}
         {--icon= : Lucide icon name for the dashboard, e.g. package}
         {--group= : Sidebar group in the dashboard}
+        {--id=uuid : What a record\'s id is: uuid, or int for the numbered ids of $table->id()}
         {--force : Overwrite an existing descriptor}
         {--migrate : Run the new migration straight away}
         {--seed= : Fill the new resource with records too (25, or the number you give). Runs the migration first}';
@@ -29,6 +30,7 @@ final class MakeResourceCommand extends Command
                 (string) ($this->option('fields') ?? $this->ask('Fields (e.g. name:string, price:money, active:boolean)')),
                 $this->option('icon'),
                 $this->option('group'),
+                (string) $this->option('id'),
             );
         } catch (InvalidArgumentException $e) {
             $this->components->error($e->getMessage());

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

@@ -175,7 +175,9 @@ final class SeedCommand extends Command
             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];
+                // An integer id is the database's to give.
+                $id = $resource->idType === 'int' ? [] : ['id' => (string) Str::uuid7()];
+                $rows[] = $id + Fake::row($resource, $offset + $i + 1, $pools) + ['created_at' => $created, 'updated_at' => $created];
             }
             DB::table($resource->table)->insert($rows);
             $bar->advance(count($rows));

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

@@ -3,6 +3,7 @@
 namespace Nevela\Laravel\Console;
 
 use Illuminate\Console\Command;
+use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Trash\Trash;
 
 final class TrashCommand extends Command
@@ -13,6 +14,13 @@ final class TrashCommand extends Command
 
     public function handle(): int
     {
+        // Files visitors uploaded for a form they never sent. Nothing to do with the trash,
+        // but the same kind of job, on the same night.
+        $unclaimed = Uploads::purgeUnclaimed();
+        if ($unclaimed > 0) {
+            $this->components->info('Removed '.number_format($unclaimed).' file(s) uploaded through a public form and never used.');
+        }
+
         $days = Trash::days();
         if ($days === null) {
             $this->components->info('Deleted records are kept until someone removes them (nevela.trash.days is off), so there is nothing to do.');