create-nevela 0.1.2 → 0.1.4

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.2';
-
-    /** @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.4';
+
+    /** @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

@@ -5,11 +5,15 @@ 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\SetupCommand;
+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;
 
@@ -24,7 +28,10 @@ final class NevelaServiceProvider extends ServiceProvider
     {
         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]);
+            $this->commands([
+                MakeResourceCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class,
+                UpdateCommand::class, DevCommand::class, StatusCommand::class, VersionCommand::class, SetupCommand::class,
+            ]);
         }
 
         $this->callAfterResolving(ExceptionHandler::class, function ($handler) {
@@ -52,6 +59,13 @@ final class NevelaServiceProvider extends ServiceProvider
             });
         }
 
+        // 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([

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

@@ -0,0 +1,118 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+/**
+ * What an app remembers about its dashboard, in apps/web/.nevela.json.
+ *
+ * - `template`: the version of the dashboard the app is on.
+ * - `files`: a fingerprint of every template file at that version. Comparing the app's
+ *   files against these is how an update tells "you changed this" from "you didn't",
+ *   with nothing to download and nothing to guess.
+ * - `dependencies`: the template's package.json dependencies at that version, for the
+ *   same question about each dependency.
+ * - `history`: what each update did.
+ *
+ * Commit the file. Backups and incoming files live beside it in .nevela/, which ignores
+ * itself.
+ */
+final class DashboardState
+{
+    /** Files the installer personalises for every app (its name); never "changed by you". */
+    public const PERSONALISED = ['package.json', 'lib/site.ts'];
+
+    /** @param array<string, string>|null $files @param array<string, array<string, string>>|null $dependencies @param list<array<string, mixed>> $history */
+    public function __construct(
+        public ?string $template = null,
+        public ?array $files = null,
+        public ?array $dependencies = null,
+        public array $history = [],
+    ) {}
+
+    public static function path(string $web): string
+    {
+        return rtrim($web, '/\\').'/.nevela.json';
+    }
+
+    public static function read(string $web): self
+    {
+        $data = json_decode((string) @file_get_contents(self::path($web)), true);
+        if (! is_array($data)) {
+            return new self;
+        }
+
+        return new self(
+            isset($data['template']) ? (string) $data['template'] : null,
+            isset($data['files']) && is_array($data['files']) ? $data['files'] : null,
+            isset($data['dependencies']) && is_array($data['dependencies']) ? $data['dependencies'] : null,
+            isset($data['history']) && is_array($data['history']) ? array_values($data['history']) : [],
+        );
+    }
+
+    public function write(string $web): void
+    {
+        $files = $this->files ?? [];
+        ksort($files);
+        file_put_contents(self::path($web), json_encode(array_filter([
+            'template' => $this->template,
+            'files' => $files ?: null,
+            'dependencies' => $this->dependencies,
+            'history' => $this->history ?: null,
+        ], fn ($value) => $value !== null), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES)."\n");
+    }
+
+    /**
+     * Record a template as the one this app is now on.
+     *
+     * @param  array<string, string>  $templateFiles  path => contents
+     */
+    public function adopt(string $version, array $templateFiles): void
+    {
+        $this->template = $version;
+        $this->files = DashboardUpdate::hashes($templateFiles);
+        $package = json_decode($templateFiles['package.json'] ?? '{}', true) ?: [];
+        $this->dependencies = array_filter([
+            'dependencies' => $package['dependencies'] ?? null,
+            'devDependencies' => $package['devDependencies'] ?? null,
+        ]);
+    }
+
+    /** The old template's package.json, as far as merging needs it, or null when it wasn't recorded. */
+    public function packageJson(): ?string
+    {
+        return $this->dependencies === null ? null : json_encode($this->dependencies);
+    }
+
+    /**
+     * The app's own fingerprints for a set of paths.
+     *
+     * @param  iterable<string>  $paths
+     * @return array<string, string|null>
+     */
+    public static function fingerprints(string $web, iterable $paths): array
+    {
+        $web = rtrim($web, '/\\');
+        $yours = [];
+        foreach ($paths as $path) {
+            $yours[$path] = is_file("{$web}/{$path}") ? DashboardUpdate::hash((string) file_get_contents("{$web}/{$path}")) : null;
+        }
+
+        return $yours;
+    }
+
+    /**
+     * The dashboard files this app has made its own, leaving out the two the installer
+     * personalises for everyone.
+     *
+     * @return array{changed: list<string>, deleted: list<string>}|null null when no fingerprints were recorded
+     */
+    public function yourChanges(string $web): ?array
+    {
+        if ($this->files === null) {
+            return null;
+        }
+        $base = array_diff_key($this->files, array_flip(self::PERSONALISED));
+
+        return DashboardUpdate::changes($base, self::fingerprints($web, array_keys($base)));
+    }
+}

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

@@ -6,7 +6,7 @@ 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
+ * Three versions of every file are compared, by fingerprint: the template the app is on
  * (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.
  */
@@ -18,19 +18,37 @@ final class DashboardUpdate
     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
+     * A file's fingerprint. Line endings are ignored: git on Windows may have rewritten
+     * them, and that is not a change anyone made.
+     */
+    public static function hash(string $contents): string
+    {
+        return sha1(str_replace("\r\n", "\n", $contents));
+    }
+
+    /**
+     * @param  array<string, string>  $contents  path => contents
+     * @return array<string, string> path => fingerprint
+     */
+    public static function hashes(array $contents): array
+    {
+        return array_map(self::hash(...), $contents);
+    }
+
+    /**
+     * @param  array<string, string>  $base  path => fingerprint, the template the app is on
+     * @param  array<string, string>  $next  path => fingerprint, the template to move to
+     * @param  array<string, string|null>  $yours  path => fingerprint of the app's file, null when it 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) {
+        foreach ($next as $path => $wanted) {
             $mine = $yours[$path] ?? null;
             $before = $base[$path] ?? null;
 
-            if ($mine !== null && self::same($mine, $contents)) {
+            if ($mine === $wanted) {
                 continue; // already there
             }
             if ($mine === null) {
@@ -41,15 +59,14 @@ final class DashboardUpdate
 
                 continue;
             }
-            if ($before !== null && self::same($before, $contents)) {
+            if ($before === $wanted) {
                 continue; // the template didn't change this file; your version stands
             }
-            $plan[$path] = $before !== null && self::same($mine, $before) ? self::UPDATE : self::CONFLICT;
+            $plan[$path] = $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)) {
+        foreach ($base as $path => $before) {
+            if (! isset($next[$path]) && ($yours[$path] ?? null) === $before) {
                 $plan[$path] = self::REMOVED;
             }
         }
@@ -59,19 +76,45 @@ final class DashboardUpdate
         return $plan;
     }
 
+    /**
+     * The files of the template that differ in the app: what the developer has made their own.
+     *
+     * @param  array<string, string>  $base  path => fingerprint, the template the app is on
+     * @param  array<string, string|null>  $yours  path => fingerprint of the app's file, null when it is missing
+     * @return array{changed: list<string>, deleted: list<string>}
+     */
+    public static function changes(array $base, array $yours): array
+    {
+        $changed = [];
+        $deleted = [];
+        foreach ($base as $path => $before) {
+            $mine = $yours[$path] ?? null;
+            if ($mine === null) {
+                $deleted[] = $path;
+            } elseif ($mine !== $before) {
+                $changed[] = $path;
+            }
+        }
+        sort($changed);
+        sort($deleted);
+
+        return ['changed' => $changed, 'deleted' => $deleted];
+    }
+
     /**
      * 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.
+     * Without the old template (`$base` null) only missing dependencies are added.
      *
      * @return array{json: string, changed: array<string, string>, kept: array<string, string>}
      */
-    public static function mergePackageJson(string $yours, string $base, string $next): array
+    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);
+        $old = $base === null ? null : json_decode($base, true, 512, JSON_THROW_ON_ERROR);
         $new = json_decode($next, true, 512, JSON_THROW_ON_ERROR);
         $changed = [];
         $kept = [];
@@ -83,7 +126,7 @@ final class DashboardUpdate
                     continue;
                 }
                 $before = $old[$section][$name] ?? null;
-                if ($mine === null || $mine === $before) {
+                if ($mine === null || ($old !== null && $mine === $before)) {
                     $app[$section][$name] = $version;
                     $changed[$name] = ($mine ?? 'not installed').' → '.$version;
                 } else {
@@ -101,10 +144,4 @@ final class DashboardUpdate
 
         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);
-    }
 }