@smi-digital/create-smi-app 2.14.2 → 2.15.0

package/dist/index.js

@@ -542,6 +542,14 @@ async function createApps(projectRoot, targets) {
           join4(projectRoot, target.directory)
         );
       });
+      await runStep(
+        "Adding the shared web-kit components",
+        async () => runCommandQuiet(
+          "npm",
+          ["install", "@smi-digital/web-kit"],
+          join4(projectRoot, target.directory)
+        )
+      );
     }
     await runSequentially(index + 1);
   };
@@ -659,9 +667,11 @@ async function createIntegrations(options, projectRoot, templatesDir) {
       await runCommandQuiet("npx", ["astro", "add", "node", "-y"], frontendDir);
       const astroConfigPath = join5(frontendDir, "astro.config.mjs");
       let astroConfig = await readFile3(astroConfigPath, "utf8");
+      const viteBlock = /(^|\n)\s*vite\s*:/v.test(astroConfig) ? "" : "\n  vite: { ssr: { noExternal: ['@smi-digital/web-kit'] } },";
       astroConfig = astroConfig.replace(
         /export default defineConfig\s*\(\s*\{/v,
-        "export default defineConfig({\n  output: 'server',"
+        `export default defineConfig({
+  output: 'server',${viteBlock}`
       );
       await writeFile3(astroConfigPath, astroConfig);
     } catch (error) {

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@smi-digital/create-smi-app",
-  "version": "2.14.2",
+  "version": "2.15.0",
   "description": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SMI-Digital/create-smi-app.git"
+  },
   "main": "dist/index.js",
   "bin": {
     "create-smi-app": "./bin/cli.js"
@@ -42,8 +46,11 @@
     "@commitlint/config-conventional": "^20.4.4",
     "@eslint/js": "^10.0.1",
     "@eslint/json": "^1.1.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@types/chalk-animation": "^1.6.3",
     "@types/node": "^25.5.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "dependency-cruiser": "^17.3.9",
     "eslint": "^10.0.3",
     "eslint-config-prettier": "^10.1.8",
@@ -53,6 +60,7 @@
     "knip": "^5.86.0",
     "lint-staged": "^16.3.3",
     "prettier": "3.8.1",
+    "semantic-release": "^25.0.9",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",

package/templates/integrations/strapi-astro/AGENTS.md.template

@@ -1,5 +1,74 @@
 # Working in this project
 
+## What this is
+
+Astro SSR (`output: "server"`, Node adapter) consuming Strapi 5 over REST at
+request time. Two independent workspaces: `frontend/` and `backend/`. There is no
+static prerendering — every page renders on demand from live CMS data, behind an
+nginx stale-while-revalidate cache.
+
+**This architecture is fixed.** If something cannot be built within it, stop and
+ask rather than changing it.
+
+## Layout
+
+```
+frontend/src/
+  components/  sections/ (static .astro)  islands/ (interactive)  ui/ (primitives)
+  layouts/     lib/     styles/     pages/     types/     assets/
+backend/src/
+  api/    extensions/    scripts/    config/
+```
+
+Each component lives in its own folder with a co-located `.module.scss`.
+Anything not listed here, read from the directory — do not assume it exists.
+
+## Running things
+
+```bash
+cd frontend   npm test | run test:watch | run lint | run build   ·  npx astro check
+cd backend    npm run develop | run build                        ·  npx tsc --noEmit
+root          npx prettier --check .                             ·  npx eslint .
+```
+
+## Non-negotiables
+
+- **CMS images go through `<CmsImage>`, local images through `<Image>`** from
+  `astro:assets`. A raw `<img>` needs a comment saying why nothing else worked.
+  → `docs/performance.md` §1
+- **Never copy code out of `@smi-digital/web-kit` into this repo.** If the shared
+  version is wrong, change the shared version. → `docs/performance.md` §7
+- **Verify against the built output, never `astro dev`.** Code splitting, CSS
+  inlining and asset optimisation only exist at build.
+- **Never commit or push.** Leave changes in the working tree.
+
+## Where to look
+
+Read the relevant file **before** starting, not after.
+
+| When you are about to… | Read |
+|---|---|
+| touch an image, font, animation, or anything that loads | `docs/performance.md` |
+| build UI — spacing, type, colour, hierarchy | `docs/design.md` |
+| disagree with a performance rule, or wonder why a budget is that number | `docs/performance-why.md` |
+| need a fact about *this* site that is not in the code | `MEMORY.md` |
+
+## Coding style
+
+- TypeScript strict everywhere; always type function return values explicitly
+- `const` over `let`, never `var`; early returns over nested conditionals
+- camelCase for variables and functions, PascalCase for components
+- SCSS Modules for component styles; never ad-hoc font sizes or colours — use the
+  scales in `frontend/src/styles/`
+- Formatting is Prettier's job, per `.prettierrc`. Do not hand-format.
+- `@/` maps to `frontend/src/`
+
+## Before assuming a library exists
+
+Read `package.json`. This is a scaffolded fleet and sites diverge — a library
+used on one site is not necessarily present on another. The same applies to
+files: check the directory rather than trusting a path you have seen elsewhere.
+
 ## The two checks that gate a pull request
 
 **The A/B visual check** builds the frontend twice — once from the merge-base,
@@ -91,6 +160,10 @@ it, and they are not interchangeable:
 
 The element is still captured and compared; freezing only pins where it sits.
 
+Separately: an animation that runs **on load** is a performance problem as well as
+an A/B one — it competes with the browser's first paint. See `docs/performance.md`
+§5.6, which is the rule that nothing may animate *into* position.
+
 ## Adding a hydration probe
 
 A screenshot cannot tell you an island stopped mounting — the server-rendered
@@ -101,13 +174,3 @@ The shared ones are `faq-accordion`, `mobile-nav` and `consent-banner`. Remove
 any this project does not have: a probe that never matches anything is reported
 as a configuration error rather than passing quietly. A project-specific probe
 means extending the shared action in `ci-library`.
-
-## Running things
-
-```bash
-npm test          # unit tests, once
-npm run test:watch
-npm run lint
-npx astro check   # types, including .astro files
-npm run build
-```

package/templates/integrations/strapi-astro/backend/config/plugins.ts.template

@@ -1,4 +1,48 @@
 export default ({ env }) => ({
+    // Media pipeline. Editors upload whatever their camera or designer produced;
+    // everything that makes it web-ready happens here, once, on upload.
+    //
+    // `breakpoints` is read by Strapi itself. The stock defaults stop at 1000px,
+    // so any viewport wider than that is handed the untouched original — which is
+    // how camera JPEGs end up in hero slots.
+    //
+    // NOTE: this applies only to NEWLY uploaded files. Existing media keeps the
+    // derivatives it was created with and must be re-processed before anything
+    // improves — see src/scripts/reprocess-media.ts.
+    upload: {
+        config: {
+            breakpoints: {
+                xsmall: 320,
+                small: 640,
+                medium: 1024,
+                large: 1600,
+                xlarge: 2400,
+            },
+            // Read by src/extensions/upload/strapi-server.ts.
+            smiImagePipeline: {
+                // Strapi never resizes the original, so a 6000x4000 upload stays
+                // 6000x4000 on disk — and is a candidate in the srcset. Cap it
+                // just above the largest breakpoint.
+                maxOriginalWidth: 2560,
+                // Most modern first. Each gets a COMPLETE ladder: a browser
+                // commits to the first <picture> source type it supports and then
+                // selects within it, so a partial AVIF ladder would hand a phone a
+                // desktop-sized file rather than falling through to a small WebP.
+                formats: [
+                    {
+                        ext: '.avif',
+                        mime: 'image/avif',
+                        options: { quality: 60, effort: 4 },
+                    },
+                    {
+                        ext: '.webp',
+                        mime: 'image/webp',
+                        options: { quality: 80 },
+                    },
+                ],
+            },
+        },
+    },
     email: {
         config: {
             provider: 'nodemailer',

package/templates/integrations/strapi-astro/backend/src/extensions/upload/strapi-server.ts.template

@@ -0,0 +1,253 @@
+/**
+ * Media pipeline: cap the original, and emit a complete AVIF + WebP ladder.
+ *
+ * Strapi resizes but never converts — JPEG in, JPEG out — so the format a
+ * visitor downloads used to be decided by whatever an editor happened to drag
+ * into the CMS. It also never touches the original, so an 11424x7616 camera
+ * file stayed 11424x7616 on disk and remained a candidate in the srcset.
+ *
+ * Two overrides on the upload plugin's image-manipulation service:
+ *
+ *   optimize()                 caps the original at maxOriginalWidth, keeping
+ *                              its source format so it stays the compatibility
+ *                              fallback on the <img>.
+ *   generateResponsiveFormats() replaces the same-format ladder with one
+ *                              COMPLETE ladder per configured format.
+ *
+ * `generateThumbnail` is a separate method and is left alone — the admin media
+ * library reads `formats.thumbnail`, so renaming ladder keys here is safe.
+ *
+ * Format keys are `<breakpoint>_<ext>` (e.g. `large_avif`). Nothing downstream
+ * parses those names: CmsImage groups derivatives by the `mime` Strapi stores
+ * on each entry, so this naming is free to change.
+ */
+import fs from 'fs';
+import path from 'path';
+import sharp, { type OutputInfo } from 'sharp';
+
+// For animated images sharp reports the true frame height as `pageHeight`, and
+// `height` is every frame stacked; without this `height` would be wildly wrong
+// on a GIF.
+//
+// Unlike the other sites in the fleet, this one does NOT need the declaration:
+// sharp 0.35 declares `pageHeight` on its own exported `OutputInfo`, and those
+// typings are in the program because this file imports the module. It is kept
+// anyway, as a no-op that costs nothing and survives a sharp downgrade — 0.33
+// and earlier have no such member, and Strapi's pinned sharp version moves.
+//
+// Note 0.35 also moved the typings entry to dist/index.d.mts, which is an ES
+// module with named exports and no `declare namespace sharp`. That is why
+// `OutputInfo` is imported as a type here rather than written `sharp.OutputInfo`
+// as the other sites do — on this version that spelling does not resolve at all.
+declare module 'sharp' {
+    interface OutputInfo {
+        pageHeight?: number;
+    }
+}
+
+interface PipelineFormat {
+    ext: string;
+    mime: string;
+    options?: Record<string, unknown>;
+}
+
+interface PipelineConfig {
+    maxOriginalWidth: number;
+    formats: PipelineFormat[];
+}
+
+const DEFAULTS: PipelineConfig = {
+    maxOriginalWidth: 2560,
+    formats: [{ ext: '.webp', mime: 'image/webp', options: { quality: 80 } }],
+};
+
+const bytesToKbytes = (bytes: number): number =>
+    Math.round((bytes / 1000) * 100) / 100;
+
+/** Sharp's method name for an extension, e.g. ".avif" -> "avif". */
+const encoderFor = (ext: string): 'avif' | 'webp' | 'jpeg' | 'png' => {
+    const name = ext.replace('.', '').toLowerCase();
+    if (name === 'jpg') return 'jpeg';
+    return name as 'avif' | 'webp' | 'jpeg' | 'png';
+};
+
+const getConfig = (): PipelineConfig => ({
+    ...DEFAULTS,
+    ...(strapi.config.get(
+        'plugin::upload.smiImagePipeline',
+        {},
+    ) as Partial<PipelineConfig>),
+});
+
+/**
+ * Resize and re-encode a file, mirroring the shape the upload plugin's own
+ * `resizeFileTo` returns. `ext`/`mime` are overridden rather than inherited,
+ * which is the whole point — the plugin's version keeps the source format.
+ */
+async function transformFile(
+    file: any,
+    {
+        resize,
+        format,
+        name,
+        hash,
+    }: {
+        resize?: { width: number; height: number };
+        format?: PipelineFormat;
+        name: string;
+        hash: string;
+    },
+): Promise<any> {
+    const filePath = file.tmpWorkingDirectory
+        ? path.join(file.tmpWorkingDirectory, hash)
+        : hash;
+
+    const build = (input?: string) => {
+        let pipeline = input
+            ? sharp(input, { animated: true })
+            : sharp({ animated: true });
+        if (resize)
+            pipeline = pipeline.resize({
+                ...resize,
+                fit: 'inside',
+                withoutEnlargement: true,
+            });
+        if (format)
+            pipeline = pipeline[encoderFor(format.ext)](format.options ?? {});
+        return pipeline;
+    };
+
+    let info: OutputInfo | undefined;
+
+    if (!file.filepath) {
+        const transform = build().on('info', (i) => {
+            info = i as OutputInfo;
+        });
+        await new Promise<void>((resolve, reject) => {
+            const writeStream = fs.createWriteStream(filePath);
+            file.getStream()
+                .pipe(transform)
+                .pipe(writeStream)
+                .on('close', resolve)
+                .on('error', reject);
+        });
+        // The `info` event does not report final byte size for a streamed encode.
+        if (info && !info.size) info.size = fs.statSync(filePath).size;
+    } else {
+        info = await build(file.filepath).toFile(filePath);
+    }
+
+    const { width, height, size, pageHeight } = (info ?? {}) as OutputInfo;
+
+    return {
+        name,
+        hash,
+        ext: format?.ext ?? file.ext,
+        mime: format?.mime ?? file.mime,
+        filepath: filePath,
+        path: file.path || null,
+        getStream: () => fs.createReadStream(filePath),
+        width,
+        height: pageHeight ?? height,
+        size: size ? bytesToKbytes(size) : 0,
+        sizeInBytes: size,
+    };
+}
+
+/** Strips the extension so a new one can be appended. */
+const baseName = (name: string, ext: string): string =>
+    name.endsWith(ext) ? name.slice(0, -ext.length) : name;
+
+export default (plugin: any) => {
+    const service = plugin.services['image-manipulation'];
+    const originalOptimize = service.optimize;
+
+    /**
+     * Cap the original. Format is deliberately preserved: with AVIF and WebP
+     * ladders in front of it, the original is what a browser supporting neither
+     * falls back to on the <img>.
+     */
+    service.optimize = async (file: any) => {
+        const optimized = await originalOptimize.call(service, file);
+        const { maxOriginalWidth } = getConfig();
+
+        if (!optimized?.width || optimized.width <= maxOriginalWidth)
+            return optimized;
+
+        const capped = await transformFile(optimized, {
+            resize: { width: maxOriginalWidth, height: maxOriginalWidth },
+            name: optimized.name,
+            hash: optimized.hash,
+        });
+
+        strapi.log.info(
+            `[media] capped ${optimized.name}: ${optimized.width}px -> ${capped.width}px`,
+        );
+        return { ...optimized, ...capped };
+    };
+
+    /**
+     * One complete ladder per configured format, replacing Strapi's
+     * same-format ladder.
+     */
+    service.generateResponsiveFormats = async (file: any) => {
+        const { responsiveDimensions = false } =
+            (await strapi.plugin('upload').service('upload').getSettings()) ??
+            {};
+        if (!responsiveDimensions) return [];
+
+        const breakpoints = strapi.config.get(
+            'plugin::upload.breakpoints',
+            {},
+        ) as Record<string, number>;
+        const { formats } = getConfig();
+        const dimensions = await service.getDimensions(file);
+        const longestEdge = Math.max(
+            dimensions.width ?? 0,
+            dimensions.height ?? 0,
+        );
+
+        const results: { key: string; file: any }[] = [];
+
+        // Every rung the original can fill, PLUS one at the original's own size.
+        //
+        // `full` is not optional. The original is stored only in its SOURCE format,
+        // so without it each converted ladder stops at the largest breakpoint below
+        // the original — and a browser that commits to the AVIF <source> can then
+        // never reach the source resolution, because <picture> never falls through
+        // to a later source. Measured on team-aha before this existed: the AVIF
+        // ladder topped out 5-29% short of the fallback on every image, worst on a
+        // 1446px-wide hero that stopped at 1024 and looked soft on a 4K display.
+        //
+        // `file` here is already the output of optimize(), so its longest edge is
+        // at most maxOriginalWidth — `full` inherits the cap rather than undoing it.
+        const rungs: { key: string; edge: number }[] = [
+            ...Object.entries(breakpoints)
+                // Skip rungs the original cannot fill — upscaling costs bytes and loses
+                // quality. Every format still gets the same set of widths, which is what
+                // <picture> selection requires.
+                .filter(([, bp]) => bp < longestEdge)
+                .map(([key, bp]) => ({ key, edge: bp })),
+            { key: 'full', edge: longestEdge },
+        ];
+
+        for (const { key, edge } of rungs) {
+            for (const format of formats) {
+                const ext = format.ext.replace('.', '');
+                results.push({
+                    key: `${key}_${ext}`,
+                    file: await transformFile(file, {
+                        resize: { width: edge, height: edge },
+                        format,
+                        name: `${key}_${baseName(file.name, file.ext)}${format.ext}`,
+                        hash: `${key}_${file.hash}_${ext}`,
+                    }),
+                });
+            }
+        }
+
+        return results;
+    };
+
+    return plugin;
+};

package/templates/integrations/strapi-astro/backend/src/scripts/reprocess-media.ts.template

@@ -0,0 +1,226 @@
+/**
+ * Re-runs the media pipeline over media that already exists.
+ *
+ * Strapi only builds derivatives on upload, so adding the pipeline (see
+ * ../extensions/upload/strapi-server.ts) improves NOTHING that is already in
+ * the library — every existing file keeps the stock 245/500/750/1000 ladder in
+ * its original format, and the frontend withholds an uncapped original from the
+ * srcset, so those images stay capped at 1000px until this runs.
+ *
+ * NOT wired into anything. Nothing imports it, `bootstrap()` does not call it,
+ * and the container runs `npm run start` — so it never fires on deploy or on
+ * boot. It is a ONE-OFF catch-up you invoke by hand, once. New uploads need it
+ * no more, because the pipeline already runs on them at upload time.
+ *
+ * Usage — open a console against the running app, then call it:
+ *
+ *   npm run console
+ *   > const { reprocessMedia } = require('./dist/src/scripts/reprocess-media');
+ *   > await reprocessMedia()                       // dry run, first 25 files
+ *   > await reprocessMedia({ apply: true })        // writes
+ *   > await reprocessMedia({ apply: true, offset: 25 })   // next batch
+ *
+ * In a dev checkout running `npm run develop`, the path is
+ * './src/scripts/reprocess-media' instead — production runs the compiled
+ * JavaScript under dist/.
+ *
+ * DRY RUN BY DEFAULT. `apply: true` is what actually writes.
+ *
+ * Take a database backup first. This rewrites the `formats` column and uploads
+ * new files through the configured provider; there is no undo.
+ *
+ * Safe to re-run: each pass regenerates from the stored original, so a partial
+ * run just gets finished by the next one. Work in batches (`limit`/`offset`) so
+ * a failure costs one batch rather than the whole library.
+ */
+
+interface ReprocessOptions {
+    /** Write. Without it the script only reports what it would do. */
+    apply?: boolean;
+    /** How many files to touch per batch. */
+    limit?: number;
+    /** Where to start. */
+    offset?: number;
+    /**
+     * Keep going until the library is exhausted (the default). Set false to run
+     * exactly one batch — useful for a cautious first pass.
+     */
+    all?: boolean;
+}
+
+interface ReprocessResult {
+    scanned: number;
+    processed: number;
+    skipped: number;
+    failed: number;
+}
+
+/** Files the pipeline cannot or should not touch. */
+const SKIP_MIME = new Set(['image/svg+xml', 'image/gif']);
+
+/**
+ * Walks the WHOLE library by default, one batch at a time.
+ *
+ * It batches internally rather than asking the caller to advance `offset`:
+ * getting that wrong is silent and looks like success, because a re-run over
+ * already-processed files reports them as `skipped` and exits happily. The
+ * first run of an offset-driven version left 13 of 30 homepage images — the LCP
+ * hero among them — unconverted for exactly that reason.
+ */
+export async function reprocessMedia(
+    options: ReprocessOptions = {},
+): Promise<ReprocessResult> {
+    const { apply = false, limit = 25, offset = 0, all = true } = options;
+
+    const total: ReprocessResult = {
+        scanned: 0,
+        processed: 0,
+        skipped: 0,
+        failed: 0,
+    };
+
+    for (let cursor = offset; ; cursor += limit) {
+        const batch = await reprocessBatch({ apply, limit, offset: cursor });
+        total.scanned += batch.scanned;
+        total.processed += batch.processed;
+        total.skipped += batch.skipped;
+        total.failed += batch.failed;
+        // A short batch means the query ran out of rows.
+        if (!all || batch.scanned < limit) break;
+    }
+
+    strapi.log.info(`[reprocess] TOTAL ${JSON.stringify(total)}`);
+    return total;
+}
+
+async function reprocessBatch(
+    options: Required<Pick<ReprocessOptions, 'apply' | 'limit' | 'offset'>>,
+): Promise<ReprocessResult> {
+    const { apply, limit, offset } = options;
+
+    const providerService = strapi.plugin('upload').service('provider');
+    const imageService = strapi.plugin('upload').service('image-manipulation');
+
+    const files = await strapi.db.query('plugin::upload.file').findMany({
+        where: { mime: { $startsWith: 'image/' } },
+        orderBy: { id: 'asc' },
+        limit,
+        offset,
+    });
+
+    const result: ReprocessResult = {
+        scanned: files.length,
+        processed: 0,
+        skipped: 0,
+        failed: 0,
+    };
+
+    strapi.log.info(
+        `[reprocess] ${apply ? 'APPLY' : 'DRY RUN'} — ${files.length} file(s), offset ${offset}`,
+    );
+
+    for (const file of files) {
+        if (SKIP_MIME.has(file.mime)) {
+            strapi.log.info(`[reprocess] skip ${file.name} (${file.mime})`);
+            result.skipped += 1;
+            continue;
+        }
+
+        // `formats` keyed `<breakpoint>_<ext>` means this file has already been
+        // through the pipeline. Re-running would be correct but wasteful.
+        const alreadyDone = Object.keys(file.formats ?? {}).some((key) =>
+            /_(avif|webp)$/v.test(key),
+        );
+        if (alreadyDone) {
+            strapi.log.info(`[reprocess] skip ${file.name} (already piped)`);
+            result.skipped += 1;
+            continue;
+        }
+
+        if (!apply) {
+            strapi.log.info(
+                `[reprocess] would reprocess ${file.name} ` +
+                    `(${file.width}x${file.height}, ${Math.round(file.size)} kB, ` +
+                    `formats: ${Object.keys(file.formats ?? {}).join(',') || 'none'})`,
+            );
+            result.processed += 1;
+            continue;
+        }
+
+        try {
+            // Mirrors what @strapi/upload's own uploadImage() does for a fresh
+            // upload: build the ladder, push each derivative through the
+            // provider, then record it under formats[key].
+            //
+            // Deliberately does NOT call optimize(). That would cap and rewrite
+            // the STORED ORIGINAL, replacing a file the provider already serves
+            // — much more invasive than this needs to be. An uncapped original
+            // is harmless now: lib/media.ts withholds it from every srcset and
+            // only keeps it as the <img src> backstop.
+            const downloaded = await fetchOriginal(file);
+            const formats =
+                await imageService.generateResponsiveFormats(downloaded);
+
+            const nextFormats: Record<string, unknown> = {
+                // Keep the stock ladder. It is still the correct fallback for a
+                // browser that supports neither AVIF nor WebP.
+                ...(file.formats ?? {}),
+            };
+            for (const entry of formats ?? []) {
+                if (!entry?.file) continue;
+                await providerService.upload(entry.file);
+                nextFormats[entry.key] = stripStream(entry.file);
+            }
+
+            await strapi.db.query('plugin::upload.file').update({
+                where: { id: file.id },
+                data: { formats: nextFormats },
+            });
+
+            strapi.log.info(
+                `[reprocess] ${file.name}: +${(formats ?? []).length} derivative(s)`,
+            );
+            result.processed += 1;
+        } catch (error) {
+            strapi.log.error(
+                `[reprocess] FAILED ${file.name}: ${(error as Error).message}`,
+            );
+            result.failed += 1;
+        }
+    }
+
+    strapi.log.info(`[reprocess] done ${JSON.stringify(result)}`);
+    return result;
+}
+
+/** The provider stores files, not streams; rehydrate one for sharp to read. */
+async function fetchOriginal(file: any): Promise<any> {
+    const { Readable } = await import('node:stream');
+    const url = file.url.startsWith('http')
+        ? file.url
+        : `${strapi.config.get('server.url', '')}${file.url}`;
+
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`GET ${url} -> ${response.status}`);
+    const buffer = Buffer.from(await response.arrayBuffer());
+
+    return {
+        ...file,
+        getStream: () => Readable.from(buffer),
+        filepath: undefined,
+    };
+}
+
+/**
+ * Format entries are persisted as JSON, so the non-serialisable bits have to go.
+ * Deleting from a shallow copy rather than destructuring-and-discarding: the
+ * latter binds three variables only to throw them away, which reads as a
+ * mistake and trips no-unused-vars.
+ */
+function stripStream(file: Record<string, unknown>): Record<string, unknown> {
+    const rest = { ...file };
+    delete rest.getStream;
+    delete rest.filepath;
+    delete rest.tmpWorkingDirectory;
+    return rest;
+}