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

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

package/templates/integrations/strapi-astro/docker-compose.yml.template

@@ -88,14 +88,14 @@ services:
       - "traefik.http.routers.__APP_NAME__-astro.rule=Host(`${PROJECT_DOMAIN}`) || Host(`www.${PROJECT_DOMAIN}`)"
       - "traefik.http.routers.__APP_NAME__-astro.tls.certresolver=letsencrypt"
       # Global middlewares (defined in webhosting-infra/traefik/dynamic)
-      - "traefik.http.routers.__APP_NAME__-astro.middlewares=secure-headers@file,rate-limit@file"
+      - "traefik.http.routers.__APP_NAME__-astro.middlewares=secure-headers@file,rate-limit@file,compress@file"
       - "traefik.http.routers.__APP_NAME__-astro.service=__APP_NAME__-cache"
       # Backend host → this same cache (Strapi behind it; /uploads cached). The
       # 25 MB upload body limit + rate-limit/secure-headers apply on this route.
       - "traefik.http.routers.__APP_NAME__-strapi.rule=Host(`${BACKEND_DOMAIN}`)"
       - "traefik.http.routers.__APP_NAME__-strapi.tls.certresolver=letsencrypt"
       - "traefik.http.middlewares.__APP_NAME__-strapi-limit.buffering.maxRequestBodyBytes=25000000"
-      - "traefik.http.routers.__APP_NAME__-strapi.middlewares=rate-limit@file,secure-headers@file,__APP_NAME__-strapi-limit"
+      - "traefik.http.routers.__APP_NAME__-strapi.middlewares=rate-limit@file,secure-headers@file,compress@file,__APP_NAME__-strapi-limit"
       - "traefik.http.routers.__APP_NAME__-strapi.service=__APP_NAME__-cache"
       # Both routers share this container's single service (Port 80), which
       # proxies to Astro / Strapi by server_name.

package/templates/integrations/strapi-astro/docs/design.md.template

@@ -0,0 +1,78 @@
+# DESIGN.md
+
+Implementation and UI design rules, imported into [CLAUDE.md](./CLAUDE.md) via `@DESIGN.md`. Split out because this section changes far more often than the architecture/tech-stack content in CLAUDE.md — edit this file directly for design-rule changes.
+
+## Implementation Rules
+
+Always use the predefined TextStyles, Paddings and Colors as defined in the project's style guide in the /styles folder.
+If a design spec (Figma file, screenshot, written brief) is given to you then always make sure to use exactly the distances/paddings, colors and textStyles it specifies. This is the most important step of the development.
+
+### Figma-to-Code Fidelity (exact-copy mode)
+
+Whenever the designer says "here's the Figma component" (or points to a specific Figma node/frame), this is a **copy task, not an inspiration task**. The designs are built almost exclusively with Auto Layout specifically so they can be translated 1:1 into code — do not "improve," simplify, or reinterpret any part of the structure he has already thought through.
+
+- **Fetch first, assume never.** Use the Figma MCP (`get_design_context` / `get_metadata` / `get_variable_defs`) to pull the actual node data before writing any markup. Never eyeball a screenshot and reconstruct structure from memory.
+- **Copy the Auto Layout structure as the div structure.** Every Auto Layout frame becomes a wrapping element with matching flex-direction, gap, alignment, and nesting depth. Do not flatten, merge, or restructure frames "because it's simpler in code" — the frame hierarchy in Figma is the source of truth for the DOM hierarchy.
+- **Copy paddings exactly**, per frame, as given by Figma — do not round to the nearest value from `_variables.scss`'s spacing scale. If an exact Figma padding doesn't map cleanly to an existing token, use the exact value (via a CSS custom value) rather than substituting the closest predefined one, and flag the mismatch.
+- **Text layers NOT inside Auto Layout** (freely positioned/absolute text) must be made **fluid/responsive to viewport width** — e.g. `clamp()` or `vw`-based sizing — instead of a fixed rem size, since Auto Layout isn't there to reflow them at different breakpoints.
+- **Never substitute your own layout idea for the given one.** If something in the Figma structure seems technically awkward to implement as specified (e.g. conflicts with SSR, an existing component, or a real constraint), stop and ask — don't quietly implement a "cleaner" version instead.
+
+### UI Design Reasoning
+
+Before implementing any UI change, work through these in order. This isn't decoration —
+skipping steps produces code that compiles and lints clean but looks wrong.
+
+#### 1. Typography — which role, why
+
+- Never set font-size/line-height/letter-spacing ad-hoc. Always use a `text-*` mixin from `_textStyles.scss`.
+- Role selection logic: `f1/f2` = fact or Number text (rare). `d1/d2/d3` = section
+  headlines, descending by section importance. `title` = card/subsection headers. `body` = paragraph text.
+  `caption` = supporting/meta text. `label` = UI chrome (buttons, tags, nav) — always `$font-mono`.
+- If a design spec's text doesn't cleanly match an existing role's size, that's a signal to ask
+  (new role needed?) — not to hardcode a one-off size.
+- If a designs spec or figma component uses a different font that can be a signal for a responsive design used in a Hero Section, ask here.
+- Weight comes from the shared `$weights` map (thin/regular/bold) — never a raw `font-weight` value.
+
+#### 2. Spacing — deliberate, not categorical
+
+- Because Capsize trims line-box whitespace, padding/margin values translate directly to visual
+  gap — there's no implicit cushion to hide an imprecise value. Treat every spacing value as exact.
+- Spacing must encode the relationship between adjacent elements, not just "which section": a
+  heading sits closer to the content it introduces than to the next unrelated block. Two elements
+  with a tight relationship (headline + its subline, label + its input) get a smaller value than
+  two elements that just happen to be stacked (end of one section, start of the next).
+- Separately, check whether the section itself is static text or animated/graphic-heavy:
+  static sections use the φ-rem spacing scale from `_variables.scss`; animated/heavy-graphic
+  sections use viewport-relative (vw) or clamped values instead, since a fixed rem value
+  breaks once the section starts moving/scaling with scroll. This is independent of the
+  relationship-based decision above — apply both.
+- If a spacing value is being picked "because it's what's used elsewhere" rather than because
+  of the actual relationship between these two specific elements, stop and reconsider.
+
+#### 3.1. Hierarchy — opacity per element type, not a flat 3-tier
+
+- Opacity is calibrated per element type, not just "primary/secondary/tertiary": e.g. H1 at 1.0,
+  H2 at ~0.9, H3 at ~0.8, The exact values depend on how many heading levels and text roles a given component has. Less Important gets less opacity.
+- Primary content (what the user should read first) stays at or near 1.0. Everything else steps
+  down based on its actual role in that specific component, not a fixed lookup table.
+- If a component has more distinct text elements at full opacity than it has genuinely
+  equal-importance messages, that's a hierarchy bug — flag it rather than implementing it as-is.
+
+#### 3.2. Hierarchy with Spacing
+
+- The Golden Spacing System is also there to help with Hierarchy.
+- Less related Objects get larger paddings, than closer related objects. Specifically with Text on Text.
+- Go bigger on Spacing than you think, because of Capsize. Also when using relative Paddings think about setting minimum borders so that text never gets cut off, or interferes with other text
+
+#### 4. Composition — preserving intent, not inventing
+
+- Identify the section's or website's focal element (its "star") — the one thing meant to hold attention.
+  When implementing, make sure any motif tied to it (shape, color, texture) that recurs
+  elsewhere in the same design is actually preserved in code — don't silently drop a
+  repeated visual detail because it's inconvenient to implement (e.g. a clipped shape reused
+  as both a card background and a button accent).
+- Depth effects (noise texture, glass/blur, parallax) must stay subtle — if an effect visually
+  competes with the focal element, that's a regression, flag it before shipping.
+- If a provided spec (design file, screenshot, written brief) conflicts with this checklist,
+  the spec wins — this section is for filling gaps or catching implementation drift, not
+  overriding what's actually provided.