create-nevela 0.1.3 → 0.1.5

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);
-    }
 }

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

@@ -0,0 +1,144 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Illuminate\Support\Facades\Http;
+use PharData;
+use RecursiveDirectoryIterator;
+use RecursiveIteratorIterator;
+use RuntimeException;
+use Throwable;
+
+/**
+ * The dashboard as it shipped in a given version of Nevela.
+ *
+ * Tried in order, so an update never depends on one place being up to date:
+ *
+ * 1. NEVELA_TEMPLATE_DIR, a folder of create-nevela-<version>.tgz files. For working on
+ *    Nevela itself, and for updating without a connection.
+ * 2. The create-nevela package on npm, which carries the dashboard.
+ * 3. The repository's own tag on GitHub. Tags are pushed before anything is published,
+ *    so this works in the gap between a release and its npm package.
+ */
+final class TemplateSource
+{
+    private const NPM = 'https://registry.npmjs.org/create-nevela/-/create-nevela-%s.tgz';
+
+    private const GITHUB = 'https://codeload.github.com/MarkColeMukisa/nevela/tar.gz/refs/tags/v%s';
+
+    /** Never part of an app's dashboard: build output, installs and local settings. */
+    private const NEVER = ['node_modules', '.next', '.env.local', 'tsconfig.tsbuildinfo', 'next-env.d.ts'];
+
+    /**
+     * @return array{files: array<string, string>, from: string} path => contents, and where it came from
+     */
+    public static function fetch(string $version): array
+    {
+        $dir = rtrim(sys_get_temp_dir(), '/\\').DIRECTORY_SEPARATOR.'nevela-template-'.$version.'-'.bin2hex(random_bytes(4));
+        mkdir($dir, 0775, true);
+        $archive = $dir.DIRECTORY_SEPARATOR.'template.tgz';
+        $tried = [];
+
+        try {
+            $local = rtrim((string) env('NEVELA_TEMPLATE_DIR', ''), '/\\');
+            if ($local !== '' && is_file("{$local}/create-nevela-{$version}.tgz")) {
+                copy("{$local}/create-nevela-{$version}.tgz", $archive);
+
+                return ['files' => self::read($archive, $dir, 'package/template/web', false), 'from' => 'NEVELA_TEMPLATE_DIR'];
+            }
+
+            foreach (['npm' => [self::NPM, 'package/template/web', false], 'GitHub' => [self::GITHUB, "nevela-{$version}/apps/web", true]] as $name => [$url, $root, $filter]) {
+                try {
+                    $response = Http::timeout(60)->get(sprintf($url, $version));
+                    if (! $response->successful()) {
+                        $tried[] = "{$name}: HTTP {$response->status()}";
+
+                        continue;
+                    }
+                    file_put_contents($archive, $response->body());
+
+                    return ['files' => self::read($archive, $dir.DIRECTORY_SEPARATOR.strtolower($name), $root, $filter), 'from' => $name];
+                } catch (Throwable $e) {
+                    $tried[] = "{$name}: ".$e->getMessage();
+                }
+            }
+
+            throw new RuntimeException("version {$version} was not found (".implode('; ', $tried).')');
+        } finally {
+            self::remove($dir);
+        }
+    }
+
+    /**
+     * Unpack an archive and read the dashboard out of it.
+     *
+     * @param  bool  $filter  Whether this is the repository's own apps/web, whose example resources aren't part of the template
+     * @return array<string, string>
+     */
+    private static function read(string $archive, string $into, string $root, bool $filter): array
+    {
+        if (! is_dir($into)) {
+            mkdir($into, 0775, true);
+        }
+        (new PharData($archive))->extractTo($into, null, true);
+        $base = $into.DIRECTORY_SEPARATOR.str_replace('/', DIRECTORY_SEPARATOR, $root);
+        if (! is_dir($base)) {
+            throw new RuntimeException('the archive has no dashboard in it');
+        }
+
+        $files = [];
+        foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($base, RecursiveDirectoryIterator::SKIP_DOTS)) as $file) {
+            $path = str_replace('\\', '/', substr($file->getPathname(), strlen($base) + 1));
+            if (array_intersect(explode('/', $path), self::NEVER) !== []) {
+                continue;
+            }
+            // npm can't carry .gitignore files, so its template holds them as _gitignore.
+            $path = preg_replace('#(^|/)_gitignore$#', '$1.gitignore', $path);
+            $files[$path] = (string) file_get_contents($file->getPathname());
+        }
+
+        return $filter ? self::withoutExamples($files) : $files;
+    }
+
+    /**
+     * The repository's dashboard has example resources in it (a Product, say). They are
+     * generated from Laravel, not part of what a new app is given.
+     *
+     * @param  array<string, string>  $files
+     * @return array<string, string>
+     */
+    public static function withoutExamples(array $files): array
+    {
+        $slugs = [];
+        foreach ($files as $path => $contents) {
+            if (preg_match('#^resources/[^/]+\.resource\.ts$#', $path) && preg_match('/slug:\s*"([^"]+)"/', $contents, $m)) {
+                $slugs[] = $m[1];
+            }
+        }
+
+        return array_filter($files, function (string $path) use ($slugs) {
+            if (preg_match('#^resources/[^/]+\.resource\.ts$#', $path) || $path === 'resources/index.ts') {
+                return false;
+            }
+            foreach ($slugs as $slug) {
+                if (str_starts_with($path, "app/dashboard/{$slug}/")) {
+                    return false;
+                }
+            }
+
+            return true;
+        }, ARRAY_FILTER_USE_KEY);
+    }
+
+    private static function remove(string $dir): void
+    {
+        if (! is_dir($dir)) {
+            return;
+        }
+        $items = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir, RecursiveDirectoryIterator::SKIP_DOTS), RecursiveIteratorIterator::CHILD_FIRST);
+        foreach ($items as $item) {
+            $item->isDir() ? @rmdir($item->getPathname()) : @unlink($item->getPathname());
+        }
+        @rmdir($dir);
+    }
+}

package/template/web/components/dashboard/dashboard-header.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState } from "react";
+import { useState, useSyncExternalStore } from "react";
 import Link from "next/link";
 import { BellIcon, MoonIcon, SunIcon } from "lucide-react";
 import { Button } from "@/components/ui/button";
@@ -30,9 +30,31 @@ function applyTheme(theme: Theme) {
   if (theme !== "system") root.classList.add(theme);
 }
 
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+
+function watchSystemTheme(onChange: () => void) {
+  const query = window.matchMedia(DARK_QUERY);
+  query.addEventListener("change", onChange);
+  return () => query.removeEventListener("change", onChange);
+}
+
+/**
+ * Whether the device prefers dark. The server can't know, so it and the first render in
+ * the browser both say no, and the real answer follows straight after: reading it during
+ * that first render would give the browser a different page from the one the server sent.
+ */
+function useSystemDark() {
+  return useSyncExternalStore(
+    watchSystemTheme,
+    () => window.matchMedia(DARK_QUERY).matches,
+    () => false,
+  );
+}
+
 export function DashboardHeader({ user, initialTheme, notices = [] }: { user: DashboardUser; initialTheme: Theme; notices?: Notice[] }) {
   const [theme, setTheme] = useState<Theme>(initialTheme);
-  const dark = theme === "dark" || (theme === "system" && typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches);
+  const systemDark = useSystemDark();
+  const dark = theme === "dark" || (theme === "system" && systemDark);
   const needsAttention = notices.some((notice) => notice.tone === "warning");
 
   return (

package/template/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nevela-web",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": true,
   "type": "module",
   "scripts": {
@@ -22,7 +22,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.4.0",
     "lucide-react": "^1.46.0",
-    "next": "16.0.4",
+    "next": "16.3.8",
     "radix-ui": "^1.6.7",
     "react": "19.3.0",
     "react-day-picker": "^10.0.1",