create-nevela 0.5.1 → 0.5.3

package/index.mjs

@@ -75,7 +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 seed | user | generate | migrate | artisan <command>
+    nevela seed | user | generate | migrate | trash | artisan <command>
 
   ${bold('Options')}
     --pm <pnpm|npm|yarn|bun>   Package manager for the dashboard. Default: the one you ran this with.
@@ -361,6 +361,10 @@ async function inProject(name, args) {
   }
   if (name !== 'upgrade') process.exit(forward(project, name, args));
 
+  // The name first, before anything that waits on the network. A newer installer this
+  // one hands over to knows it has been shown, and prints one line in its place.
+  showTitle();
+
   // Upgrading is the one command that must not run on stale code itself: it is the newest
   // installer that knows what an older app needs repaired. So even a nevela command that
   // hasn't been updated in a while upgrades an app correctly.
@@ -371,9 +375,22 @@ async function inProject(name, args) {
       if (status !== null) process.exit(status);
     }
   }
-  console.log(`\n  ${indigo(bold('Nevela'))} ${dim('upgrade')}\n`);
+  const before = appVersion(project);
+  const looking = args.includes('--check') ? ' (checking only: nothing will be changed)' : '';
+  console.log(`  ${indigo(`Nevela upgrade — this app: ${before ? `v${before}` : 'Nevela not installed in it yet'}`)}${dim(looking)}\n`);
   const releases = await latestRelease();
   const status = await upgrade(project, args, { latest: releases, say: (line) => console.log(`  ${green('✔')} ${line}`) });
+  // Where it ended up, read from the app itself and not from what was asked for.
+  if (status === 0 && !args.includes('--check') && !args.includes('--undo')) {
+    const now = appVersion(project);
+    if (now) {
+      console.log(`\n  ${green(`✔ ${now === before ? `This app is on Nevela v${now}, the version it was on.` : `This app is now on Nevela v${now}.`}`)}\n`);
+    }
+    // A release is on Packagist a few minutes before every Composer can see it. Finishing
+    // on the older one without a word would look like there was nothing newer.
+    const behind = behindNotice(now, releases);
+    if (behind) console.log(`${behind}\n`);
+  }
   process.exit(status);
 }
 
@@ -435,6 +452,19 @@ function otherCopies() {
   for (const removal of removals) console.log(`      ${bold(removal)}`);
 }
 
+/**
+ * What to say when an upgrade finished on a version older than the newest release, or null
+ * when it didn't. `now` is what the app has, `latest` what Packagist lists.
+ */
+function behindNotice(now, latest) {
+  if (!now || !latest || !isNewer(latest, now)) return null;
+  return [
+    `  ${red('!')} Nevela ${bold(`v${latest}`)} is out, and Composer didn't bring it in.`,
+    `    A release takes a few minutes to reach Composer. Run ${bold('nevela upgrade')} again shortly.`,
+    `    ${dim(`Still on v${now} after that? This says what holds it back: cd apps/api && composer why-not nevela/laravel ${latest}`)}`,
+  ].join('\n');
+}
+
 /** The version of Nevela an app has installed, read from the package, or null. */
 function appVersion(project) {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevela",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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'];
+const NEVELA = ['upgrade', 'dev', 'status', 'version', 'resource', '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

@@ -114,6 +114,22 @@ return [
     'per_page' => 25,
     'max_per_page' => 100,
 
+    /*
+    | The trash. A deleted record is kept, hidden from every list and count, and can be
+    | restored from the dashboard's Trash page for this many days. Then it is removed for
+    | good: each night by `nevela:trash`, which needs Laravel's scheduler running, and
+    | whenever someone opens the trash. Null keeps deleted records until someone removes them.
+    */
+    'trash' => [
+        'days' => 30,
+    ],
+
+    /*
+    | 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.
+    */
+    'bulk_max' => 500,
+
     /*
     | File and image fields (image:image, manual:file(pdf)).
     |

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

@@ -0,0 +1,63 @@
+<?php
+
+namespace Nevela\Laravel\Concerns;
+
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Support\Facades\Schema;
+use Nevela\Laravel\Trash\TrashedScope;
+
+/**
+ * A model whose deleted records go to the trash, where they can be restored for a while.
+ *
+ * This is Laravel's own soft delete, with one difference: it only takes effect once the
+ * table has its `deleted_at` column. An app that has upgraded and not yet migrated keeps
+ * working exactly as before, with delete meaning delete, where plain SoftDeletes would
+ * put `deleted_at is null` into every query on a table that has no such column.
+ *
+ * Every generated model uses it. Everything Laravel's soft delete offers is here:
+ * `$model->restore()`, `$model->forceDelete()`, `$model->trashed()`, and on a query
+ * `withTrashed()` and `onlyTrashed()`.
+ *
+ * @mixin \Illuminate\Database\Eloquent\Model
+ */
+trait Trashable
+{
+    use SoftDeletes;
+
+    /** Whether this model's table has somewhere to keep a deleted record. Only "yes" is remembered. */
+    private static bool $hasTrash = false;
+
+    public static function trashes(): bool
+    {
+        if (static::$hasTrash) {
+            return true;
+        }
+        $model = new static;
+
+        // The column can arrive later in the same process (a migration run from a command),
+        // so "no" is asked again and "yes" is kept.
+        return static::$hasTrash = Schema::connection($model->getConnectionName())->hasColumn($model->getTable(), $model->getDeletedAtColumn());
+    }
+
+    /** Ask the database again next time. For a test that adds or drops the column within one process. */
+    public static function forgetTrash(): void
+    {
+        static::$hasTrash = false;
+    }
+
+    /** In place of SoftDeletes' own: the same scope, applied only where there is a trash. */
+    public static function bootSoftDeletes(): void
+    {
+        static::addGlobalScope(new TrashedScope);
+    }
+
+    public static function bootTrashable(): void
+    {
+        // With no column to mark it in, a delete removes the row, as it always did.
+        static::deleting(function (self $model) {
+            if (! static::trashes()) {
+                $model->forceDeleting = true;
+            }
+        });
+    }
+}

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

@@ -3,6 +3,7 @@
 namespace Nevela\Laravel\Console;
 
 use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Schema;
 use InvalidArgumentException;
 use Nevela\Laravel\Generator\ResourceGenerator;
 use Nevela\Laravel\Generator\Writer;
@@ -17,6 +18,41 @@ final class GenerateCommand extends Command
 
     protected $description = 'Regenerate Laravel code and Flare descriptors from nevela/resources/*.json';
 
+    /**
+     * Whether a resource's table needs the migration that gives it a trash.
+     *
+     * Not when its own migration already makes the column, and not when the column is
+     * there without one of ours having been written: then it came from a migration of
+     * the app's own, and ours would take that column away again when rolled back.
+     *
+     * @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
+     */
+    public static function needsTrashMigration(array $createMigrations, bool $written, bool $columnExists): bool
+    {
+        if ($createMigrations === []) {
+            return false;
+        }
+        foreach ($createMigrations as $contents) {
+            if (preg_match('/softDeletes|deleted_at/', $contents) === 1) {
+                return false;
+            }
+        }
+
+        return $written || ! $columnExists;
+    }
+
+    /** Whether the table has the column now. No, where there is no database to ask. */
+    private static function hasTrashColumn(string $table): bool
+    {
+        try {
+            return Schema::hasColumn($table, 'deleted_at');
+        } catch (\Throwable) {
+            return false;
+        }
+    }
+
     public function handle(): int
     {
         Nevela::forget();
@@ -87,6 +123,13 @@ final class GenerateCommand extends Command
         $files = [];
         foreach ($queue as $descriptor) {
             array_push($files, ...$generator->forResource($descriptor, null, $all));
+            // A table made before there was a trash gets a migration that gives it one. A new
+            // 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))) {
+                $files[] = $generator->trashMigrationFile($descriptor);
+            }
         }
         $files[] = $generator->routes($all);
         $files[] = $generator->registry($all);

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

@@ -0,0 +1,33 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Nevela\Laravel\Trash\Trash;
+
+final class TrashCommand extends Command
+{
+    protected $signature = 'nevela:trash';
+
+    protected $description = 'Remove, for good, the deleted records whose time in the trash has run out';
+
+    public function handle(): int
+    {
+        $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.');
+
+            return self::SUCCESS;
+        }
+
+        $removed = Trash::purgeExpired();
+        foreach ($removed as $resource => $count) {
+            $this->components->twoColumnDetail($resource, number_format($count).' removed');
+        }
+        $this->components->info($removed === []
+            ? "Nothing in the trash is older than {$days} days."
+            : 'Removed '.number_format(array_sum($removed))." record(s) deleted more than {$days} days ago.");
+
+        return self::SUCCESS;
+    }
+}

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

@@ -226,7 +226,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'];
+        \$nevela = ['resource', 'generate', 'seed', 'user', 'upgrade', 'update', 'dev', 'status', 'version', 'trash'];
         \$artisan = ['migrate', 'tinker', 'test', 'serve'];
         if (in_array(\$name, ['--version', '-v', '-V'], true)) {
             \$name = 'version';
@@ -255,6 +255,7 @@ final class ResourceGenerator
               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
+              php nevela trash                 remove deleted records whose time in the trash is up
               php nevela upgrade               bring this app to the latest Nevela
               php nevela version               which Nevela this is
 
@@ -382,6 +383,8 @@ final class ResourceGenerator
         foreach ($all as $d) {
             $controller = "\\App\\Http\\Controllers\\Api\\{$d->name}Controller::class";
             $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});";
         }
         $body = implode("\n", $lines);
@@ -461,6 +464,9 @@ final class ResourceGenerator
             protected \$table = '{$d->table}';
 
             {$m}
+            // Deleted records go to the trash, where they can be restored for a while.
+            use \Nevela\Laravel\Concerns\Trashable;
+
             protected \$fillable = [{$fillable}];
 
             protected function casts(): array
@@ -533,6 +539,8 @@ final class ResourceGenerator
                     \$table->uuid('id')->primary();
         {$cols}
                     \$table->timestamps();
+                    // When a record was deleted. Until it is removed for good it sits in the trash.
+                    \$table->softDeletes();
                 });
             }
 
@@ -545,6 +553,55 @@ final class ResourceGenerator
         PHP;
     }
 
+    /**
+     * For a table made before there was a trash: the column that gives it one.
+     *
+     * Written once, by `nevela:generate`, for a resource whose own migration doesn't
+     * have the column. Until it is run, deleting a record removes it as before.
+     */
+    public function trashMigration(Descriptor $d): string
+    {
+        return <<<PHP
+        <?php
+
+        use Illuminate\Database\Migrations\Migration;
+        use Illuminate\Database\Schema\Blueprint;
+        use Illuminate\Support\Facades\Schema;
+
+        // Gives {$d->pluralLabel} a trash: a deleted record is kept, hidden, and can be restored
+        // for a while (config/nevela.php, trash.days). Generated once by Nevela.
+        return new class extends Migration
+        {
+            public function up(): void
+            {
+                if (Schema::hasTable('{$d->table}') && ! Schema::hasColumn('{$d->table}', 'deleted_at')) {
+                    Schema::table('{$d->table}', function (Blueprint \$table) {
+                        \$table->softDeletes();
+                    });
+                }
+            }
+
+            public function down(): void
+            {
+                if (Schema::hasColumn('{$d->table}', 'deleted_at')) {
+                    Schema::table('{$d->table}', function (Blueprint \$table) {
+                        \$table->dropSoftDeletes();
+                    });
+                }
+            }
+        };
+
+        PHP;
+    }
+
+    /** The file `trashMigration()` goes in. Not made again once one exists for the table, whatever its date. */
+    public function trashMigrationFile(Descriptor $d, ?string $timestamp = null): GeneratedFile
+    {
+        $timestamp ??= date('Y_m_d_His');
+
+        return new GeneratedFile(GeneratedFile::TARGET_API, "database/migrations/{$timestamp}_add_trash_to_{$d->table}_table.php", $this->trashMigration($d), GeneratedFile::MODE_ONCE, "database/migrations/*_add_trash_to_{$d->table}_table.php");
+    }
+
     /** @param list<Descriptor> $all */
     public function request(Descriptor $d, array $all = []): string
     {
@@ -749,6 +806,13 @@ final class ResourceGenerator
                 return Nevela::stats({$d->name}::query(), '{$d->name}', \$request);
             }
 
+            public function insights(Request \$request): JsonResponse
+            {
+                Gate::authorize('viewAny', {$d->name}::class);
+
+                return Nevela::insights({$d->name}::query(), '{$d->name}', \$request);
+            }
+
             public function store({$d->name}Request \$request): JsonResponse
             {
                 \${$var} = {$d->name}::create(\$request->values());
@@ -759,6 +823,13 @@ final class ResourceGenerator
                     ->header('Location', \$request->url().'/'.\${$var}->getKey());
             }
 
+            public function bulk(Request \$request): JsonResponse
+            {
+                Gate::authorize('create', {$d->name}::class);
+
+                return Nevela::createMany({$d->name}::class, {$d->name}Request::class, {$d->name}Resource::class, \$request);
+            }
+
             public function show({$d->name} \${$var}): {$d->name}Resource
             {
                 Gate::authorize('view', \${$var});
@@ -836,6 +907,18 @@ final class ResourceGenerator
             {
                 return \$user->can('{$d->table}.delete');
             }
+
+            /** Bring a deleted one back from the trash. */
+            public function restore(User \$user, {$d->name} \${$var}): bool
+            {
+                return \$user->can('{$d->table}.delete');
+            }
+
+            /** Remove a deleted one from the trash, for good. */
+            public function forceDelete(User \$user, {$d->name} \${$var}): bool
+            {
+                return \$user->can('{$d->table}.delete');
+            }
         }
 
         PHP;

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

@@ -3,6 +3,10 @@
 namespace Nevela\Laravel\Http;
 
 use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Facades\Validator as Validation;
+use Illuminate\Validation\Rules\Unique;
 use Illuminate\Validation\Validator;
 
 /**
@@ -49,9 +53,113 @@ abstract class ResourceRequest extends FormRequest
                     $validator->errors()->add((string) $key, 'Unknown field.');
                 }
             }
+            self::explainTrashed($validator, $validator->getData());
         });
     }
 
+    /**
+     * A unique value can be held by a record nobody can see: one in the trash. "Already
+     * taken" would send someone looking through a list it isn't in, so say where it is.
+     *
+     * @param  array<string, mixed>  $data
+     * @return list<array{path: string, message: string}> The messages that were replaced
+     */
+    private static function explainTrashed(Validator $validator, array $data): array
+    {
+        $replaced = [];
+        foreach ($validator->failed() as $field => $rules) {
+            // What Laravel gives for a failed unique rule: the table and the column it looked in.
+            [$table, $column] = array_pad($rules['Unique'] ?? [], 2, null);
+            $value = $data[$field] ?? null;
+            if (! is_string($table) || ! is_string($column) || ! is_scalar($value) || $column === 'NULL') {
+                continue;
+            }
+            if (! Schema::hasColumn($table, 'deleted_at') || ! DB::table($table)->where($column, $value)->whereNotNull('deleted_at')->exists()) {
+                continue;
+            }
+            $message = 'This belongs to a record in the trash. Restore that record, or delete it for good to use the value again.';
+            $validator->errors()->forget($field);
+            $validator->errors()->add($field, $message);
+            $replaced[] = ['path' => (string) $field, 'message' => $message];
+        }
+
+        return $replaced;
+    }
+
+    /**
+     * Many rows, each checked by the rules for creating one.
+     *
+     * The same rules as a single create, on purpose: a second way into the table with its
+     * own idea of what is valid would let through a row the form then refuses to save.
+     * Rows are numbered from 1, as a person counts them.
+     *
+     * Two rows of one batch can't share a unique value either. The database would refuse
+     * the second, but only after the first was written and with no row number to show.
+     *
+     * @param  list<mixed>  $rows
+     * @return array{values: list<array<string, mixed>>, problems: list<array{row: int, issues: list<array{path: string, message: string}>}>}
+     */
+    public function many(array $rows): array
+    {
+        $rules = $this->rules();
+        $columns = $this->columns();
+        $known = array_keys($columns);
+        $computed = array_map(fn (string $field) => $field.'File', $known);
+        $unique = array_keys(array_filter($rules, fn ($rule) => is_array($rule) && array_filter($rule, fn ($one) => $one instanceof Unique) !== []));
+
+        $values = [];
+        $problems = [];
+        $taken = [];
+        foreach (array_values($rows) as $index => $row) {
+            $number = $index + 1;
+            if (! is_array($row) || array_is_list($row)) {
+                // An empty JSON object arrives as an empty list; anything else here is not fields at all.
+                $problems[] = ['row' => $number, 'issues' => [['path' => '', 'message' => $row === [] ? 'This row is empty.' : 'This row is not a record.']]];
+
+                continue;
+            }
+            $issues = [];
+            foreach (array_keys($row) as $key) {
+                if (! in_array($key, $known, true) && ! in_array($key, self::READ_ONLY, true) && ! in_array($key, $computed, true)) {
+                    $issues[] = ['path' => (string) $key, 'message' => 'Unknown field.'];
+                }
+            }
+            $validator = Validation::make($row, $rules);
+            if ($validator->fails()) {
+                self::explainTrashed($validator, $row);
+                array_push($issues, ...FlareErrors::issues($validator->errors()->toArray()));
+            }
+            foreach ($unique as $field) {
+                $value = $row[$field] ?? null;
+                if (! is_scalar($value) || (string) $value === '') {
+                    continue;
+                }
+                $mark = $field."\0".$value;
+                if (isset($taken[$mark])) {
+                    $issues[] = ['path' => $field, 'message' => "The same as row {$taken[$mark]}. Each one needs its own."];
+                } else {
+                    $taken[$mark] = $number;
+                }
+            }
+            if ($issues !== []) {
+                $problems[] = ['row' => $number, 'issues' => $issues];
+
+                continue;
+            }
+
+            $validated = $validator->validated();
+            $mapped = [];
+            foreach ($columns as $field => $column) {
+                if (array_key_exists($field, $validated)) {
+                    $mapped[$column] = $validated[$field];
+                }
+            }
+            $values[] = $mapped;
+        }
+
+        return ['values' => $values, 'problems' => $problems];
+    }
+
     /** Validated input keyed by column, ready for create()/update(). @return array<string, mixed> */
     public function values(): array
     {