create-nevela 0.1.1 → 0.1.3

package/template/laravel/src/Nevela.php

@@ -1,151 +1,161 @@
-<?php
-
-namespace Nevela\Laravel;
-
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
-use InvalidArgumentException;
-use Nevela\Laravel\Support\Descriptor;
-use Nevela\Laravel\Support\ListQuery;
-use Nevela\Laravel\Support\Naming;
-
-/**
- * Runtime helpers the generated controllers call. Kept small and readable: each method is
- * one step of Flare's REST contract.
- */
-final class Nevela
-{
-    /** Written by `pnpm release`; the same number as the repository's git tag. */
-    public const VERSION = '0.1.1';
-
-    /** @var array<string, Descriptor> */
-    private static array $descriptors = [];
-
-    /** A resource's descriptor, from config('nevela.descriptors_path')/<kebab-name>.json. */
-    public static function resource(string $name): Descriptor
-    {
-        if (isset(self::$descriptors[$name])) {
-            return self::$descriptors[$name];
-        }
-        $path = rtrim(config('nevela.descriptors_path'), '/\\').DIRECTORY_SEPARATOR.Naming::kebab($name).'.json';
-        if (! is_file($path)) {
-            throw new InvalidArgumentException("No Nevela descriptor for {$name} at {$path}.");
-        }
-
-        return self::$descriptors[$name] = Descriptor::fromJson((string) file_get_contents($path));
-    }
-
-    /** @return list<Descriptor> */
-    public static function all(): array
-    {
-        $dir = config('nevela.descriptors_path');
-        $all = [];
-        foreach (glob(rtrim($dir, '/\\').DIRECTORY_SEPARATOR.'*.json') ?: [] as $file) {
-            $d = Descriptor::fromJson((string) file_get_contents($file));
-            $all[] = self::$descriptors[$d->name] = $d;
-        }
-
-        return $all;
-    }
-
-    public static function forget(): void
-    {
-        self::$descriptors = [];
-    }
-
-    /**
-     * GET /{slug}: page, perPage, sort, q, filter[field] → { data, meta }.
-     *
-     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
-     */
-    public static function list(Builder $query, string $name, Request $request, string $resourceClass): JsonResponse
-    {
-        $resource = self::resource($name);
-        $list = ListQuery::parse($resource, $request->query(), (int) config('nevela.per_page', 25), (int) config('nevela.max_per_page', 100));
-        if (! $list->ok()) {
-            return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
-        }
-
-        if ($list->q !== null) {
-            $columns = array_map(fn ($f) => $f->column(), array_values(array_filter($resource->fields, fn ($f) => $f->searchable())));
-            if ($columns !== []) {
-                $pattern = '%'.addcslashes($list->q, '%_\\').'%';
-                $query->where(function (Builder $where) use ($columns, $pattern) {
-                    foreach ($columns as $column) {
-                        $where->orWhereLike($column, $pattern);
-                    }
-                });
-            }
-        }
-
-        foreach ($list->filters as $filter) {
-            $filter['value'] === null
-                ? $query->whereNull($filter['column'])
-                : $query->where($filter['column'], $filter['value']);
-        }
-
-        $query->reorder()
-            ->orderBy($list->sort['column'], $list->sort['direction'])
-            ->orderBy($query->getModel()->getKeyName(), $list->sort['direction']);
-
-        $page = $query->paginate($list->perPage, ['*'], 'page', $list->page);
-
-        return response()->json([
-            'data' => $resourceClass::collection($page->getCollection())->resolve($request),
-            'meta' => [
-                'page' => $page->currentPage(),
-                'perPage' => $page->perPage(),
-                'total' => $page->total(),
-                'totalPages' => max(1, $page->lastPage()),
-            ],
-        ]);
-    }
-
-    /**
-     * GET /{slug}/_stats?field=status&days=7 → { total, current, previous, values }.
-     * What Flare's ResourceStats card shows above a table.
-     */
-    public static function stats(Builder $query, string $name, Request $request): JsonResponse
-    {
-        $resource = self::resource($name);
-        $days = filter_var($request->query('days', 7), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => 365]]);
-        if ($days === false) {
-            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'days', 'message' => 'Must be between 1 and 365.']]], 400);
-        }
-        $key = $request->query('field');
-        $field = is_string($key) ? ($resource->fields[$key] ?? null) : null;
-        if ($key !== null && ($field === null || ! in_array($field->kind, ['enum', 'boolean'], true))) {
-            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'field', 'message' => 'Must be an enum or boolean field.']]], 400);
-        }
-
-        $now = now();
-        $since = $now->copy()->subDays($days);
-        $before = $now->copy()->subDays($days * 2);
-        $base = fn () => (clone $query)->reorder();
-
-        $values = [];
-        if ($field !== null) {
-            $column = $field->column();
-            foreach ($base()->toBase()->select($column.' as value')->selectRaw('count(*) as aggregate')->groupBy($column)->get() as $row) {
-                $value = $field->kind === 'boolean' ? ($row->value ? 'true' : 'false') : (string) $row->value;
-                $values[$value] = (int) $row->aggregate;
-            }
-        }
-
-        return response()->json([
-            'total' => $base()->count(),
-            'current' => $base()->where('created_at', '>=', $since)->count(),
-            'previous' => $base()->where('created_at', '>=', $before)->where('created_at', '<', $since)->count(),
-            'values' => (object) $values,
-        ]);
-    }
-
-    /** Whether a request is one Nevela answers (so errors use Flare's shape). */
-    public static function handles(Request $request): bool
-    {
-        $prefix = trim((string) config('nevela.prefix', 'api'), '/');
-
-        return $prefix === '' || $request->is($prefix, $prefix.'/*');
-    }
-}
+<?php
+
+namespace Nevela\Laravel;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use InvalidArgumentException;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\ListQuery;
+use Nevela\Laravel\Support\Naming;
+
+/**
+ * Runtime helpers the generated controllers call. Kept small and readable: each method is
+ * one step of Flare's REST contract.
+ */
+final class Nevela
+{
+    /** Written by `pnpm release`; the same number as the repository's git tag. */
+    public const VERSION = '0.1.3';
+
+    /** @var array<string, Descriptor> */
+    private static array $descriptors = [];
+
+    /**
+     * A short id for this installation, from where it is on disk. It gives nothing away,
+     * and it differs between two apps on one machine, which is what it is for: telling
+     * which app is answering on a port.
+     */
+    public static function fingerprint(): string
+    {
+        return substr(sha1(base_path()), 0, 12);
+    }
+
+    /** A resource's descriptor, from config('nevela.descriptors_path')/<kebab-name>.json. */
+    public static function resource(string $name): Descriptor
+    {
+        if (isset(self::$descriptors[$name])) {
+            return self::$descriptors[$name];
+        }
+        $path = rtrim(config('nevela.descriptors_path'), '/\\').DIRECTORY_SEPARATOR.Naming::kebab($name).'.json';
+        if (! is_file($path)) {
+            throw new InvalidArgumentException("No Nevela descriptor for {$name} at {$path}.");
+        }
+
+        return self::$descriptors[$name] = Descriptor::fromJson((string) file_get_contents($path));
+    }
+
+    /** @return list<Descriptor> */
+    public static function all(): array
+    {
+        $dir = config('nevela.descriptors_path');
+        $all = [];
+        foreach (glob(rtrim($dir, '/\\').DIRECTORY_SEPARATOR.'*.json') ?: [] as $file) {
+            $d = Descriptor::fromJson((string) file_get_contents($file));
+            $all[] = self::$descriptors[$d->name] = $d;
+        }
+
+        return $all;
+    }
+
+    public static function forget(): void
+    {
+        self::$descriptors = [];
+    }
+
+    /**
+     * GET /{slug}: page, perPage, sort, q, filter[field] → { data, meta }.
+     *
+     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
+     */
+    public static function list(Builder $query, string $name, Request $request, string $resourceClass): JsonResponse
+    {
+        $resource = self::resource($name);
+        $list = ListQuery::parse($resource, $request->query(), (int) config('nevela.per_page', 25), (int) config('nevela.max_per_page', 100));
+        if (! $list->ok()) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
+        }
+
+        if ($list->q !== null) {
+            $columns = array_map(fn ($f) => $f->column(), array_values(array_filter($resource->fields, fn ($f) => $f->searchable())));
+            if ($columns !== []) {
+                $pattern = '%'.addcslashes($list->q, '%_\\').'%';
+                $query->where(function (Builder $where) use ($columns, $pattern) {
+                    foreach ($columns as $column) {
+                        $where->orWhereLike($column, $pattern);
+                    }
+                });
+            }
+        }
+
+        foreach ($list->filters as $filter) {
+            $filter['value'] === null
+                ? $query->whereNull($filter['column'])
+                : $query->where($filter['column'], $filter['value']);
+        }
+
+        $query->reorder()
+            ->orderBy($list->sort['column'], $list->sort['direction'])
+            ->orderBy($query->getModel()->getKeyName(), $list->sort['direction']);
+
+        $page = $query->paginate($list->perPage, ['*'], 'page', $list->page);
+
+        return response()->json([
+            'data' => $resourceClass::collection($page->getCollection())->resolve($request),
+            'meta' => [
+                'page' => $page->currentPage(),
+                'perPage' => $page->perPage(),
+                'total' => $page->total(),
+                'totalPages' => max(1, $page->lastPage()),
+            ],
+        ]);
+    }
+
+    /**
+     * GET /{slug}/_stats?field=status&days=7 → { total, current, previous, values }.
+     * What Flare's ResourceStats card shows above a table.
+     */
+    public static function stats(Builder $query, string $name, Request $request): JsonResponse
+    {
+        $resource = self::resource($name);
+        $days = filter_var($request->query('days', 7), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => 365]]);
+        if ($days === false) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'days', 'message' => 'Must be between 1 and 365.']]], 400);
+        }
+        $key = $request->query('field');
+        $field = is_string($key) ? ($resource->fields[$key] ?? null) : null;
+        if ($key !== null && ($field === null || ! in_array($field->kind, ['enum', 'boolean'], true))) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'field', 'message' => 'Must be an enum or boolean field.']]], 400);
+        }
+
+        $now = now();
+        $since = $now->copy()->subDays($days);
+        $before = $now->copy()->subDays($days * 2);
+        $base = fn () => (clone $query)->reorder();
+
+        $values = [];
+        if ($field !== null) {
+            $column = $field->column();
+            foreach ($base()->toBase()->select($column.' as value')->selectRaw('count(*) as aggregate')->groupBy($column)->get() as $row) {
+                $value = $field->kind === 'boolean' ? ($row->value ? 'true' : 'false') : (string) $row->value;
+                $values[$value] = (int) $row->aggregate;
+            }
+        }
+
+        return response()->json([
+            'total' => $base()->count(),
+            'current' => $base()->where('created_at', '>=', $since)->count(),
+            'previous' => $base()->where('created_at', '>=', $before)->where('created_at', '<', $since)->count(),
+            'values' => (object) $values,
+        ]);
+    }
+
+    /** Whether a request is one Nevela answers (so errors use Flare's shape). */
+    public static function handles(Request $request): bool
+    {
+        $prefix = trim((string) config('nevela.prefix', 'api'), '/');
+
+        return $prefix === '' || $request->is($prefix, $prefix.'/*');
+    }
+}

package/template/laravel/src/NevelaServiceProvider.php

@@ -1,65 +1,79 @@
-<?php
-
-namespace Nevela\Laravel;
-
-use Illuminate\Contracts\Debug\ExceptionHandler;
-use Illuminate\Support\Facades\Route;
-use Illuminate\Support\ServiceProvider;
-use Nevela\Laravel\Console\GenerateCommand;
-use Nevela\Laravel\Console\MakeResourceCommand;
-use Nevela\Laravel\Console\SeedCommand;
-use Nevela\Laravel\Console\UserCommand;
-use Nevela\Laravel\Http\FlareErrors;
-use Nevela\Laravel\Http\TokenController;
-
-final class NevelaServiceProvider extends ServiceProvider
-{
-    public function register(): void
-    {
-        $this->mergeConfigFrom(__DIR__.'/../config/nevela.php', 'nevela');
-    }
-
-    public function boot(): void
-    {
-        if ($this->app->runningInConsole()) {
-            $this->publishes([__DIR__.'/../config/nevela.php' => config_path('nevela.php')], 'nevela-config');
-            $this->commands([MakeResourceCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class]);
-        }
-
-        $this->callAfterResolving(ExceptionHandler::class, function ($handler) {
-            if (method_exists($handler, 'renderable')) {
-                $handler->renderable(fn (\Throwable $e, $request) => FlareErrors::render($e, $request));
-            }
-        });
-
-        if (! $this->app->routesAreCached()) {
-            $this->registerRoutes();
-        }
-    }
-
-    private function registerRoutes(): void
-    {
-        $prefix = config('nevela.prefix', 'api');
-
-        if (config('nevela.auth.enabled', true)) {
-            Route::prefix($prefix)->middleware('api')->name('nevela.auth.')->group(function () {
-                Route::post('auth/token', [TokenController::class, 'store'])->middleware('throttle:6,1')->name('store');
-                Route::middleware('auth:sanctum')->group(function () {
-                    Route::get('auth/me', [TokenController::class, 'show'])->name('show');
-                    Route::delete('auth/token', [TokenController::class, 'destroy'])->name('destroy');
-                });
-            });
-        }
-
-        Route::prefix($prefix)->middleware(config('nevela.middleware', ['api', 'auth:sanctum']))->name('nevela.')->group(function () {
-            // The descriptors, so the web app (and tooling) can check it matches the API.
-            Route::get('_nevela/resources', fn () => response()->json([
-                'data' => array_map(fn ($d) => $d->toArray(), Nevela::all()),
-            ]))->name('resources');
-
-            if (is_file($routes = base_path('routes/nevela.php'))) {
-                require $routes;
-            }
-        });
-    }
-}
+<?php
+
+namespace Nevela\Laravel;
+
+use Illuminate\Contracts\Debug\ExceptionHandler;
+use Illuminate\Support\Facades\Route;
+use Illuminate\Support\ServiceProvider;
+use Nevela\Laravel\Console\DevCommand;
+use Nevela\Laravel\Console\GenerateCommand;
+use Nevela\Laravel\Console\MakeResourceCommand;
+use Nevela\Laravel\Console\SeedCommand;
+use Nevela\Laravel\Console\StatusCommand;
+use Nevela\Laravel\Console\UpdateCommand;
+use Nevela\Laravel\Console\UserCommand;
+use Nevela\Laravel\Console\VersionCommand;
+use Nevela\Laravel\Http\FlareErrors;
+use Nevela\Laravel\Http\TokenController;
+
+final class NevelaServiceProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->mergeConfigFrom(__DIR__.'/../config/nevela.php', 'nevela');
+    }
+
+    public function boot(): void
+    {
+        if ($this->app->runningInConsole()) {
+            $this->publishes([__DIR__.'/../config/nevela.php' => config_path('nevela.php')], 'nevela-config');
+            $this->commands([
+                MakeResourceCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class,
+                UpdateCommand::class, DevCommand::class, StatusCommand::class, VersionCommand::class,
+            ]);
+        }
+
+        $this->callAfterResolving(ExceptionHandler::class, function ($handler) {
+            if (method_exists($handler, 'renderable')) {
+                $handler->renderable(fn (\Throwable $e, $request) => FlareErrors::render($e, $request));
+            }
+        });
+
+        if (! $this->app->routesAreCached()) {
+            $this->registerRoutes();
+        }
+    }
+
+    private function registerRoutes(): void
+    {
+        $prefix = config('nevela.prefix', 'api');
+
+        if (config('nevela.auth.enabled', true)) {
+            Route::prefix($prefix)->middleware('api')->name('nevela.auth.')->group(function () {
+                Route::post('auth/token', [TokenController::class, 'store'])->middleware('throttle:6,1')->name('store');
+                Route::middleware('auth:sanctum')->group(function () {
+                    Route::get('auth/me', [TokenController::class, 'show'])->name('show');
+                    Route::delete('auth/token', [TokenController::class, 'destroy'])->name('destroy');
+                });
+            });
+        }
+
+        // Open to anyone, and says only that this is a Nevela app and which one. It is how the
+        // dashboard and `nevela:status` tell this app from another program on the same port.
+        Route::prefix($prefix)->middleware(['api', 'throttle:60,1'])->get('_nevela/ping', fn () => response()->json([
+            'nevela' => Nevela::VERSION,
+            'app' => Nevela::fingerprint(),
+        ]))->name('nevela.ping');
+
+        Route::prefix($prefix)->middleware(config('nevela.middleware', ['api', 'auth:sanctum']))->name('nevela.')->group(function () {
+            // The descriptors, so the web app (and tooling) can check it matches the API.
+            Route::get('_nevela/resources', fn () => response()->json([
+                'data' => array_map(fn ($d) => $d->toArray(), Nevela::all()),
+            ]))->name('resources');
+
+            if (is_file($routes = base_path('routes/nevela.php'))) {
+                require $routes;
+            }
+        });
+    }
+}

package/template/laravel/src/Support/DashboardUpdate.php

@@ -0,0 +1,110 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+/**
+ * Works out how to bring an app's dashboard up to a newer template without losing what
+ * the developer changed.
+ *
+ * Three versions of every file are compared: the template the app was created from
+ * (base), the newer template (next) and what is in the app now (yours). Only a file the
+ * developer hasn't touched is replaced. Pure on purpose: no filesystem, no network.
+ */
+final class DashboardUpdate
+{
+    public const UPDATE = 'update';      // you didn't change it; the template did
+    public const ADD = 'add';            // new in the template
+    public const CONFLICT = 'conflict';  // you changed it and so did the template
+    public const REMOVED = 'removed';    // gone from the template; you still have it unchanged
+
+    /**
+     * @param  array<string, string>  $base  path => contents, the template the app started from
+     * @param  array<string, string>  $next  path => contents, the template to move to
+     * @param  array<string, string|null>  $yours  path => contents in the app, null when the file is missing
+     * @return array<string, string> path => one of the constants above. Files needing nothing are left out.
+     */
+    public static function plan(array $base, array $next, array $yours): array
+    {
+        $plan = [];
+        foreach ($next as $path => $contents) {
+            $mine = $yours[$path] ?? null;
+            $before = $base[$path] ?? null;
+
+            if ($mine !== null && self::same($mine, $contents)) {
+                continue; // already there
+            }
+            if ($mine === null) {
+                // Not in the app. Add it if it is new; leave it out if you deleted it.
+                if ($before === null) {
+                    $plan[$path] = self::ADD;
+                }
+
+                continue;
+            }
+            if ($before !== null && self::same($before, $contents)) {
+                continue; // the template didn't change this file; your version stands
+            }
+            $plan[$path] = $before !== null && self::same($mine, $before) ? self::UPDATE : self::CONFLICT;
+        }
+
+        foreach ($base as $path => $contents) {
+            $mine = $yours[$path] ?? null;
+            if (! isset($next[$path]) && $mine !== null && self::same($mine, $contents)) {
+                $plan[$path] = self::REMOVED;
+            }
+        }
+
+        ksort($plan);
+
+        return $plan;
+    }
+
+    /**
+     * Move the app's package.json to the template's dependency versions, keeping its name
+     * and anything else the developer added.
+     *
+     * A dependency is moved when the app still has the version the old template had, or
+     * doesn't have it at all. One the developer pinned differently is left and reported.
+     *
+     * @return array{json: string, changed: array<string, string>, kept: array<string, string>}
+     */
+    public static function mergePackageJson(string $yours, string $base, string $next): array
+    {
+        $app = json_decode($yours, true, 512, JSON_THROW_ON_ERROR);
+        $old = json_decode($base, true, 512, JSON_THROW_ON_ERROR);
+        $new = json_decode($next, true, 512, JSON_THROW_ON_ERROR);
+        $changed = [];
+        $kept = [];
+
+        foreach (['dependencies', 'devDependencies'] as $section) {
+            foreach ($new[$section] ?? [] as $name => $version) {
+                $mine = $app[$section][$name] ?? null;
+                if ($mine === $version) {
+                    continue;
+                }
+                $before = $old[$section][$name] ?? null;
+                if ($mine === null || $mine === $before) {
+                    $app[$section][$name] = $version;
+                    $changed[$name] = ($mine ?? 'not installed').' → '.$version;
+                } else {
+                    $kept[$name] = "{$mine} (template: {$version})";
+                }
+            }
+            if (isset($app[$section])) {
+                ksort($app[$section]);
+            }
+        }
+
+        // npm's own formatting: two spaces, unescaped slashes, a trailing newline.
+        $json = json_encode($app, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+        $json = preg_replace_callback('/^( {4})+/m', fn ($m) => str_repeat('  ', strlen($m[0]) / 4), $json);
+
+        return ['json' => $json."\n", 'changed' => $changed, 'kept' => $kept];
+    }
+
+    /** Equal apart from line endings: git on Windows may have rewritten them. */
+    public static function same(string $a, string $b): bool
+    {
+        return $a === $b || str_replace("\r\n", "\n", $a) === str_replace("\r\n", "\n", $b);
+    }
+}

package/template/laravel/src/Support/Releases.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Illuminate\Support\Facades\Http;
+use Throwable;
+
+/** What Packagist knows about nevela/laravel. */
+final class Releases
+{
+    private static string|null|false $latest = false;
+
+    /** The newest stable release, or null when Packagist can't be reached. Asked once per run. */
+    public static function latest(): ?string
+    {
+        if (self::$latest !== false) {
+            return self::$latest;
+        }
+        try {
+            $releases = Http::timeout(8)->get('https://repo.packagist.org/p2/nevela/laravel.json')->json('packages.nevela/laravel') ?? [];
+        } catch (Throwable) {
+            return self::$latest = null;
+        }
+
+        return self::$latest = self::newest(array_map(fn ($release) => (string) ($release['version'] ?? ''), $releases));
+    }
+
+    /**
+     * The highest x.y.z in a list of version names. Branches and pre-releases don't count.
+     *
+     * @param  list<string>  $names
+     */
+    public static function newest(array $names): ?string
+    {
+        $versions = [];
+        foreach ($names as $name) {
+            if (preg_match('/^v?(\d+\.\d+\.\d+)$/', $name, $m)) {
+                $versions[] = $m[1];
+            }
+        }
+        usort($versions, 'version_compare');
+
+        return $versions === [] ? null : end($versions);
+    }
+}