create-nevela 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,77 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use InvalidArgumentException;
+use Nevela\Laravel\Generator\ResourceGenerator;
+use Nevela\Laravel\Generator\Writer;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+
+final class GenerateCommand extends Command
+{
+    protected $signature = 'nevela:generate
+        {name? : Only this resource (e.g. Product). Default: every descriptor}
+        {--force : Rewrite generated blocks even where you edited inside them}';
+
+    protected $description = 'Regenerate Laravel code and Flare descriptors from nevela/resources/*.json';
+
+    public function handle(): int
+    {
+        Nevela::forget();
+        try {
+            $all = Nevela::all();
+            $targets = $this->argument('name') ? [Nevela::resource($this->argument('name'))] : $all;
+        } catch (InvalidArgumentException $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+        // With no descriptors there is still an (empty) route file and web registry to
+        // write, so a new app's dashboard builds before its first resource exists.
+        $status = self::generate($this, $targets, $all, (bool) $this->option('force'));
+        if ($all === []) {
+            $this->components->warn('No descriptors yet. Start with: php artisan nevela:resource Product --fields="name:string, price:money"');
+        }
+
+        return $status;
+    }
+
+    /** @param list<Descriptor> $targets @param list<Descriptor> $all */
+    public static function generate(Command $command, array $targets, array $all, bool $force): int
+    {
+        $generator = new ResourceGenerator;
+        $files = [];
+        foreach ($targets as $descriptor) {
+            array_push($files, ...$generator->forResource($descriptor));
+        }
+        $files[] = $generator->routes($all);
+        $files[] = $generator->registry($all);
+
+        $roots = ['api' => base_path()];
+        if (($web = config('nevela.web_path')) && is_dir($web)) {
+            $roots['web'] = $web;
+        }
+
+        $report = (new Writer($roots, $force))->write($files);
+        $edited = 0;
+        foreach ($report as $row) {
+            $path = str_replace([base_path().DIRECTORY_SEPARATOR, '\\'], ['', '/'], $row['path']);
+            $command->components->twoColumnDetail($path, match ($row['status']) {
+                'created' => '<fg=green>created</>',
+                'updated' => '<fg=blue>updated</>',
+                'edited' => '<fg=yellow>skipped — edited inside generated block</>',
+                'exists' => '<fg=gray>exists (yours)</>',
+                'skipped' => '<fg=gray>skipped (no web app at nevela.web_path yet)</>',
+                default => '<fg=gray>unchanged</>',
+            });
+            $edited += $row['status'] === 'edited' ? 1 : 0;
+        }
+        if ($edited) {
+            $command->components->warn("{$edited} file(s) skipped because you edited their generated block. Move your changes outside it, or rerun with --force.");
+        }
+
+        return self::SUCCESS;
+    }
+}

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

@@ -0,0 +1,66 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use InvalidArgumentException;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Naming;
+
+final class MakeResourceCommand extends Command
+{
+    protected $signature = 'nevela:resource
+        {name : PascalCase resource name, e.g. Product}
+        {--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}
+        {--force : Overwrite an existing descriptor}';
+
+    protected $description = 'Describe a resource once, then generate its Laravel API and Flare dashboard descriptor';
+
+    public function handle(): int
+    {
+        try {
+            $descriptor = Descriptor::fromSpec(
+                $this->argument('name'),
+                (string) ($this->option('fields') ?? $this->ask('Fields (e.g. name:string, price:money, active:boolean)')),
+                $this->option('icon'),
+                $this->option('group'),
+            );
+        } catch (InvalidArgumentException $e) {
+            $this->components->error($e->getMessage());
+
+            return self::FAILURE;
+        }
+
+        $dir = rtrim(config('nevela.descriptors_path'), '/\\');
+        $path = $dir.DIRECTORY_SEPARATOR.Naming::kebab($descriptor->name).'.json';
+        if (is_file($path) && ! $this->option('force')) {
+            $this->components->error("{$descriptor->name} already has a descriptor. Edit it and run: php artisan nevela:generate {$descriptor->name}");
+
+            return self::FAILURE;
+        }
+        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</>, then tighten <fg=cyan>app/Policies/'.$descriptor->name.'Policy.php</>.');
+        $this->line("  API:  GET|POST /{$this->prefix()}{$descriptor->slug} · GET|PUT|PATCH|DELETE /{$this->prefix()}{$descriptor->slug}/{id} · GET /{$this->prefix()}{$descriptor->slug}/_stats");
+
+        return $status;
+    }
+
+    private function prefix(): string
+    {
+        $prefix = trim((string) config('nevela.prefix', 'api'), '/');
+
+        return $prefix === '' ? '' : $prefix.'/';
+    }
+}

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

@@ -0,0 +1,124 @@
+<?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;
+    }
+}

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

@@ -0,0 +1,59 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Validator;
+
+final class UserCommand extends Command
+{
+    protected $signature = 'nevela:user
+        {--name= : The person\'s name}
+        {--email= : The address they sign in with}
+        {--password= : Their password. Leave out to be asked for it without it showing}';
+
+    protected $description = 'Create a user who can sign in to the dashboard';
+
+    public function handle(): int
+    {
+        $model = config('auth.providers.users.model');
+        if (! is_string($model) || ! class_exists($model)) {
+            $this->components->error('No user model is configured in config/auth.php (auth.providers.users.model).');
+
+            return self::FAILURE;
+        }
+
+        $input = [
+            'name' => $this->option('name') ?? $this->ask('Name'),
+            'email' => $this->option('email') ?? $this->ask('Email'),
+            'password' => $this->option('password') ?? $this->secret('Password (at least 8 characters)'),
+        ];
+
+        $table = (new $model)->getTable();
+        $validator = Validator::make($input, [
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['required', 'email', 'max:255', "unique:{$table},email"],
+            'password' => ['required', 'string', 'min:8'],
+        ]);
+        if ($validator->fails()) {
+            foreach ($validator->errors()->all() as $message) {
+                $this->components->error($message);
+            }
+
+            return self::FAILURE;
+        }
+
+        // forceFill: this is the operator creating an account, not a form to guard.
+        $user = (new $model)->forceFill([
+            'name' => $input['name'],
+            'email' => $input['email'],
+            'password' => Hash::make($input['password']),
+        ]);
+        $user->save();
+
+        $this->components->info("Created {$input['email']}. They can sign in to the dashboard now.");
+
+        return self::SUCCESS;
+    }
+}

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

@@ -0,0 +1,31 @@
+<?php
+
+namespace Nevela\Laravel\Generator;
+
+/**
+ * One file the generator wants to exist.
+ *
+ * - MODE_BLOCK: the file carries a `nevela:generated:start … end` block. Regeneration
+ *   rewrites only that block; everything outside it is yours. If you edited inside the
+ *   block, regeneration skips the file (the hash no longer matches) unless forced.
+ * - MODE_ONCE: written when missing, never touched again (migrations, policies).
+ */
+final class GeneratedFile
+{
+    public const MODE_BLOCK = 'block';
+
+    public const MODE_ONCE = 'once';
+
+    public const TARGET_API = 'api';
+
+    public const TARGET_WEB = 'web';
+
+    public function __construct(
+        public readonly string $target,
+        public readonly string $path,
+        public readonly string $contents,
+        public readonly string $mode = self::MODE_BLOCK,
+        /** For MODE_ONCE: a glob (relative to the target root) that, when it matches, means the file already exists under another name. */
+        public readonly ?string $existsGlob = null,
+    ) {}
+}