create-nevela 0.1.3 → 0.1.4

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nevela-web",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "scripts": {

package/template.mjs

@@ -1,94 +1,127 @@
-// Where the new app's files come from.
-//
-// Published to npm, this package carries a `template/` folder built by build-template.mjs.
-// Run from the repository, it reads apps/web and packages/laravel directly, so there is
-// one source for the dashboard and nothing to keep in sync by hand.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const here = path.dirname(fileURLToPath(import.meta.url));
-const bundled = path.join(here, 'template');
-const fromRepo = !fs.existsSync(bundled);
-
-export const sources = {
-  web: fromRepo ? path.resolve(here, '..', '..', 'apps', 'web') : path.join(bundled, 'web'),
-  laravel: fromRepo ? path.resolve(here, '..', 'laravel') : path.join(bundled, 'laravel'),
-};
-
-/** Never part of a new app: build output, installs and local settings. */
-const NEVER = new Set(['node_modules', '.next', '.env.local', 'tsconfig.tsbuildinfo', 'next-env.d.ts', 'vendor', '.phpunit.result.cache', '.phpunit.cache', 'composer.lock']);
-
-function copyTree(from, to, skip = () => false, relative = '') {
-  fs.mkdirSync(to, { recursive: true });
-  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-    const inside = relative ? `${relative}/${entry.name}` : entry.name;
-    if (NEVER.has(entry.name) || skip(inside, entry)) continue;
-    const source = path.join(from, entry.name);
-    // npm leaves .gitignore files out of a published package, so the bundled template
-    // carries them as _gitignore (see buildTemplate) and they get their name back here.
-    const target = path.join(to, entry.name === '_gitignore' ? '.gitignore' : entry.name);
-    if (entry.isDirectory()) copyTree(source, target, skip, inside);
-    else if (entry.isFile()) fs.copyFileSync(source, target);
-  }
-}
-
-/**
- * What belongs to the framework repository's own example resources, not to a new app:
- * their descriptors, the registry that lists them, and their dashboard pages.
- */
-export function exampleResourceFilter(webRoot) {
-  const resources = path.join(webRoot, 'resources');
-  const slugs = new Set();
-  if (fs.existsSync(resources)) {
-    for (const file of fs.readdirSync(resources)) {
-      if (!file.endsWith('.resource.ts')) continue;
-      const slug = /slug:\s*"([^"]+)"/.exec(fs.readFileSync(path.join(resources, file), 'utf8'));
-      if (slug) slugs.add(slug[1]);
-    }
-  }
-  return (inside) =>
-    /^resources\/[^/]+\.resource\.ts$/.test(inside)
-    || inside === 'resources/index.ts'
-    || [...slugs].some((slug) => inside === `app/dashboard/${slug}`);
-}
-
-/** The dashboard, without the repository's example resources, named for the new app. */
-export function copyWebTemplate(to, { name, title }) {
-  copyTree(sources.web, to, exampleResourceFilter(sources.web));
-
-  const packageFile = path.join(to, 'package.json');
-  const manifest = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
-  manifest.name = `${name}-web`;
-  fs.writeFileSync(packageFile, `${JSON.stringify(manifest, null, 2)}\n`);
-
-  const siteFile = path.join(to, 'lib', 'site.ts');
-  const site = fs.readFileSync(siteFile, 'utf8')
-    .replace('name: "Nevela"', `name: ${JSON.stringify(title)}`)
-    .replace('description: "Nevela keeps', `description: "${title.replace(/"/g, '')} keeps`);
-  fs.writeFileSync(siteFile, site);
-
-  // The generator fills this in; it has to exist for the first build.
-  fs.mkdirSync(path.join(to, 'resources'), { recursive: true });
-}
-
-/** The Laravel package, for installing by path until it is on Packagist. */
-export function copyLaravelPackage(to) {
-  copyTree(sources.laravel, to, (inside) => inside === 'tests' || inside === 'phpunit.xml');
-}
-
-/** Used by build-template.mjs: the same filtered copies, into this package's template/. */
-export function buildTemplate(to) {
-  copyTree(sources.web, path.join(to, 'web'), exampleResourceFilter(sources.web));
-  copyLaravelPackage(path.join(to, 'laravel'));
-  hideGitignores(to);
-}
-
-function hideGitignores(dir) {
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) hideGitignores(full);
-    else if (entry.name === '.gitignore') fs.renameSync(full, path.join(dir, '_gitignore'));
-  }
-}
+// Where the new app's files come from.
+//
+// Published to npm, this package carries a `template/` folder built by build-template.mjs.
+// Run from the repository, it reads apps/web and packages/laravel directly, so there is
+// one source for the dashboard and nothing to keep in sync by hand.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const bundled = path.join(here, 'template');
+// In a checkout the dashboard two folders up is the source, even when a template/ folder
+// is lying around from an earlier `npm pack`: that copy may be stale.
+const fromRepo = fs.existsSync(path.resolve(here, '..', '..', 'apps', 'web', 'package.json')) || !fs.existsSync(bundled);
+
+/** True when this is a checkout of the repository rather than the package from npm. */
+export const fromRepository = fromRepo;
+
+export const sources = {
+  web: fromRepo ? path.resolve(here, '..', '..', 'apps', 'web') : path.join(bundled, 'web'),
+  laravel: fromRepo ? path.resolve(here, '..', 'laravel') : path.join(bundled, 'laravel'),
+};
+
+/** Never part of a new app: build output, installs and local settings. */
+const NEVER = new Set(['node_modules', '.next', '.env.local', 'tsconfig.tsbuildinfo', 'next-env.d.ts', 'vendor', '.phpunit.result.cache', '.phpunit.cache', 'composer.lock']);
+
+function copyTree(from, to, skip = () => false, relative = '') {
+  fs.mkdirSync(to, { recursive: true });
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    const inside = relative ? `${relative}/${entry.name}` : entry.name;
+    if (NEVER.has(entry.name) || skip(inside, entry)) continue;
+    const source = path.join(from, entry.name);
+    // npm leaves .gitignore files out of a published package, so the bundled template
+    // carries them as _gitignore (see buildTemplate) and they get their name back here.
+    const target = path.join(to, entry.name === '_gitignore' ? '.gitignore' : entry.name);
+    if (entry.isDirectory()) copyTree(source, target, skip, inside);
+    else if (entry.isFile()) fs.copyFileSync(source, target);
+  }
+}
+
+/**
+ * What belongs to the framework repository's own example resources, not to a new app:
+ * their descriptors, the registry that lists them, and their dashboard pages.
+ */
+export function exampleResourceFilter(webRoot) {
+  const resources = path.join(webRoot, 'resources');
+  const slugs = new Set();
+  if (fs.existsSync(resources)) {
+    for (const file of fs.readdirSync(resources)) {
+      if (!file.endsWith('.resource.ts')) continue;
+      const slug = /slug:\s*"([^"]+)"/.exec(fs.readFileSync(path.join(resources, file), 'utf8'));
+      if (slug) slugs.add(slug[1]);
+    }
+  }
+  return (inside) =>
+    /^resources\/[^/]+\.resource\.ts$/.test(inside)
+    || inside === 'resources/index.ts'
+    || [...slugs].some((slug) => inside === `app/dashboard/${slug}`);
+}
+
+/** The dashboard, without the repository's example resources, named for the new app. */
+export function copyWebTemplate(to, { name, title }) {
+  copyTree(sources.web, to, exampleResourceFilter(sources.web));
+
+  const packageFile = path.join(to, 'package.json');
+  const manifest = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+  manifest.name = `${name}-web`;
+  fs.writeFileSync(packageFile, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  const siteFile = path.join(to, 'lib', 'site.ts');
+  const site = fs.readFileSync(siteFile, 'utf8')
+    .replace('name: "Nevela"', `name: ${JSON.stringify(title)}`)
+    .replace('description: "Nevela keeps', `description: "${title.replace(/"/g, '')} keeps`);
+  fs.writeFileSync(siteFile, site);
+
+  // The generator fills this in; it has to exist for the first build.
+  fs.mkdirSync(path.join(to, 'resources'), { recursive: true });
+}
+
+/**
+ * A fingerprint of every template file, and the template's dependencies: what the app
+ * records in .nevela.json so that `nevela update` can tell, later and exactly, which
+ * files the developer changed. The same fingerprint the Laravel package computes: SHA-1
+ * with line endings ignored.
+ */
+export function templateRecord(version) {
+  const skip = exampleResourceFilter(sources.web);
+  const files = {};
+  const walk = (dir, relative = '') => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const inside = relative ? `${relative}/${entry.name}` : entry.name;
+      if (NEVER.has(entry.name) || skip(inside, entry)) continue;
+      if (entry.isDirectory()) walk(path.join(dir, entry.name), inside);
+      else if (entry.isFile()) {
+        const bytes = fs.readFileSync(path.join(dir, entry.name)).toString('latin1').replace(/\r\n/g, '\n');
+        files[inside.replace(/(^|\/)_gitignore$/, '$1.gitignore')] = crypto.createHash('sha1').update(bytes, 'latin1').digest('hex');
+      }
+    }
+  };
+  walk(sources.web);
+  const manifest = JSON.parse(fs.readFileSync(path.join(sources.web, 'package.json'), 'utf8'));
+  const dependencies = {};
+  for (const section of ['dependencies', 'devDependencies']) if (manifest[section]) dependencies[section] = manifest[section];
+  return { template: version, files: Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b))), dependencies };
+}
+
+/** The Laravel package, for installing by path until it is on Packagist. */
+export function copyLaravelPackage(to) {
+  copyTree(sources.laravel, to, (inside) => inside === 'tests' || inside === 'phpunit.xml');
+}
+
+/** Used by build-template.mjs: the same filtered copies, into this package's template/. */
+export function buildTemplate(to) {
+  copyTree(sources.web, path.join(to, 'web'), exampleResourceFilter(sources.web));
+  copyLaravelPackage(path.join(to, 'laravel'));
+  hideGitignores(to);
+}
+
+function hideGitignores(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) hideGitignores(full);
+    else if (entry.name === '.gitignore') fs.renameSync(full, path.join(dir, '_gitignore'));
+  }
+}