@megabudino/stack-utils 1.4.0 → 1.5.0

package/README.md

@@ -49,8 +49,7 @@ Proxy config:
 | --- | --- | --- | --- |
 | `originUrl` | `string` | required | Origin server URL |
 | `siteUrl` | `string` | required | Public site URL |
-| `sitemaps` | `string[]` | `[]` | SvelteKit sitemap URLs to inject into sitemap indexes |
-| `sitemapCacheSeconds` | `number` | `3600` | Cache max-age for sitemap responses |
+| `sitemap` | `SitemapConfig` | `{}` | Sitemap index injection and origin URL filtering |
 | `proxyAssets` | `boolean` | `false` | Rewrite origin asset URLs to relative paths |
 | `additionalOrigins` | `string[]` | `[]` | Additional absolute origins to rewrite like `originUrl` |
 | `domActions` | `DomAction[]` | `[]` | Declarative DOM transformations for proxied HTML |
@@ -61,7 +60,7 @@ What it does:
 - lets SvelteKit routes resolve normally when a route exists
 - proxies unmatched requests to the configured origin
 - rewrites redirects back to the public domain
-- rewrites HTML, applies optional DOM actions, and injects extra sitemap entries when configured
+- rewrites HTML, applies optional DOM actions, and rewrites sitemap XML when configured
 
 ### `images`
 
@@ -99,18 +98,24 @@ What it does:
 - reads source images from `static/images`
 - writes responsive variants to `static/_image-variants`
 - writes its generated manifest to `.stack-utils/image-variants.generated.json`
+- writes cache metadata to `.stack-utils/image-variants.cache.json`
 - rewrites compatible `<img src="/images/...">` tags to an internal `StaticImage` component
 - keeps `StaticImage` internal to the package so the public API stays small
 
-### Consumer gitignore
+### Reusing built images
 
-In the consuming app, ignore the generated pipeline output:
+If you want to build the image variants once and reuse them across machines or CI runs, commit:
 
-```gitignore
-static/_image-variants
-.stack-utils
+```text
+static/_image-variants/
+.stack-utils/image-variants.generated.json
+.stack-utils/image-variants.cache.json
 ```
 
+The pipeline will hash the current source images, verify the referenced generated files still exist, and skip regeneration when everything matches.
+
+If you prefer generated artifacts to stay local, you can still ignore those paths in the consuming app.
+
 ## Publishing Notes
 
 The package is intended to be consumed via subpath imports:

package/dist/images/config.d.ts

@@ -4,6 +4,7 @@ export declare const staticImagePipelineConfig: {
     readonly publicSourcePrefix: "/images";
     readonly publicOutputPrefix: "/_image-variants";
     readonly manifestPath: ".stack-utils/image-variants.generated.json";
+    readonly cachePath: ".stack-utils/image-variants.cache.json";
     readonly supportedExtensions: readonly [".jpg", ".jpeg", ".png", ".webp"];
     readonly widths: readonly [320, 480, 640, 768, 960, 1280, 1536, 1920];
     readonly quality: {

package/dist/images/config.js

@@ -4,6 +4,7 @@ export const staticImagePipelineConfig = {
     publicSourcePrefix: '/images',
     publicOutputPrefix: '/_image-variants',
     manifestPath: '.stack-utils/image-variants.generated.json',
+    cachePath: '.stack-utils/image-variants.cache.json',
     supportedExtensions: ['.jpg', '.jpeg', '.png', '.webp'],
     widths: [320, 480, 640, 768, 960, 1280, 1536, 1920],
     quality: {

package/dist/images/generator.js

@@ -1,20 +1,37 @@
-import { promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { createReadStream, promises as fs } from 'node:fs';
 import path from 'node:path';
 import sharp from 'sharp';
 import { staticImagePipelineConfig } from './config.js';
 const SUPPORTED_EXTENSIONS = new Set(staticImagePipelineConfig.supportedExtensions);
+const IMAGE_VARIANT_CACHE_VERSION = 1;
 export async function generateStaticImageVariants({ root, log = () => undefined }) {
     const sourceDirectory = path.join(root, staticImagePipelineConfig.sourceDirectory);
     const outputDirectory = path.join(root, staticImagePipelineConfig.outputDirectory);
     const manifestPath = path.join(root, staticImagePipelineConfig.manifestPath);
+    const cachePath = path.join(root, staticImagePipelineConfig.cachePath);
     await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+    await fs.mkdir(path.dirname(cachePath), { recursive: true });
     const sourceFiles = await collectSourceImages(sourceDirectory);
+    const cacheMetadata = await buildCacheMetadata(sourceFiles);
     if (sourceFiles.length === 0) {
         await fs.mkdir(outputDirectory, { recursive: true });
         await fs.writeFile(manifestPath, '{}\n');
+        await fs.writeFile(cachePath, `${JSON.stringify(cacheMetadata, null, 2)}\n`);
         return {};
     }
     await fs.mkdir(outputDirectory, { recursive: true });
+    const reusableManifest = await readReusableManifest({
+        root,
+        sourceFiles,
+        manifestPath,
+        cachePath,
+        cacheMetadata
+    });
+    if (reusableManifest) {
+        log(`[static-image-pipeline] reused ${Object.keys(reusableManifest).length} manifest entries`);
+        return reusableManifest;
+    }
     const manifest = {};
     for (const file of sourceFiles) {
         const entry = await generateManifestEntry({ file, outputDirectory });
@@ -23,9 +40,34 @@ export async function generateStaticImageVariants({ root, log = () => undefined
         }
     }
     await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    await fs.writeFile(cachePath, `${JSON.stringify(cacheMetadata, null, 2)}\n`);
     log(`[static-image-pipeline] generated ${Object.keys(manifest).length} manifest entries`);
     return manifest;
 }
+async function readReusableManifest({ root, sourceFiles, manifestPath, cachePath, cacheMetadata }) {
+    const [manifest, persistedCache] = await Promise.all([
+        readJsonFile(manifestPath),
+        readJsonFile(cachePath)
+    ]);
+    if (!manifest || !persistedCache) {
+        return null;
+    }
+    if (persistedCache.version !== IMAGE_VARIANT_CACHE_VERSION) {
+        return null;
+    }
+    if (persistedCache.configHash !== cacheMetadata.configHash) {
+        return null;
+    }
+    if (!areStringRecordsEqual(persistedCache.sources, cacheMetadata.sources)) {
+        return null;
+    }
+    if (!manifestMatchesSources(manifest, sourceFiles)) {
+        return null;
+    }
+    const outputFiles = getOutputFilesFromManifest(root, manifest);
+    const outputFilesExist = await allFilesExist(outputFiles);
+    return outputFilesExist ? manifest : null;
+}
 async function generateManifestEntry({ file, outputDirectory }) {
     const image = sharp(file.absolutePath, { failOn: 'none' });
     const metadata = await image.metadata();
@@ -146,6 +188,22 @@ async function collectSourceImages(directory) {
     files.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
     return files;
 }
+async function buildCacheMetadata(sourceFiles) {
+    const sources = Object.fromEntries(await Promise.all(sourceFiles.map(async (file) => [toSourcePath(file.relativePath), await hashFile(file.absolutePath)])));
+    return {
+        version: IMAGE_VARIANT_CACHE_VERSION,
+        configHash: createHash('sha1')
+            .update(JSON.stringify({
+            outputDirectory: staticImagePipelineConfig.outputDirectory,
+            publicOutputPrefix: staticImagePipelineConfig.publicOutputPrefix,
+            widths: staticImagePipelineConfig.widths,
+            quality: staticImagePipelineConfig.quality,
+            supportedExtensions: staticImagePipelineConfig.supportedExtensions
+        }))
+            .digest('hex'),
+        sources
+    };
+}
 async function walkDirectory(directory, onFile, baseDirectory = directory) {
     let entries;
     try {
@@ -179,10 +237,71 @@ async function needsWrite(outputPath, sourceMtimeMs) {
         throw error;
     }
 }
+async function hashFile(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha1');
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+        stream.on('error', reject);
+    });
+}
+async function readJsonFile(filePath) {
+    try {
+        const fileContents = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(fileContents);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+function areStringRecordsEqual(left, right) {
+    const leftEntries = Object.entries(left).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+    const rightEntries = Object.entries(right).sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+    if (leftEntries.length !== rightEntries.length) {
+        return false;
+    }
+    return leftEntries.every(([leftKey, leftValue], index) => leftKey === rightEntries[index]?.[0] && leftValue === rightEntries[index]?.[1]);
+}
+function manifestMatchesSources(manifest, sourceFiles) {
+    const manifestSources = Object.keys(manifest).sort((left, right) => left.localeCompare(right));
+    const expectedSources = sourceFiles
+        .map((file) => toSourcePath(file.relativePath))
+        .sort((left, right) => left.localeCompare(right));
+    if (manifestSources.length !== expectedSources.length) {
+        return false;
+    }
+    return manifestSources.every((sourcePath, index) => sourcePath === expectedSources[index]);
+}
+async function allFilesExist(filePaths) {
+    for (const filePath of filePaths) {
+        try {
+            await fs.stat(filePath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return false;
+            }
+            throw error;
+        }
+    }
+    return true;
+}
 function getTargetWidths(originalWidth) {
     const widths = staticImagePipelineConfig.widths.filter((width) => width < originalWidth).map(Number);
     return Array.from(new Set([...widths, originalWidth])).sort((left, right) => left - right);
 }
+function getOutputFilesFromManifest(root, manifest) {
+    return Object.values(manifest).flatMap((entry) => Object.values(entry.formats).flatMap((variants) => variants.map((variant) => {
+        const outputRelativePath = variant.url
+            .replace(`${staticImagePipelineConfig.publicOutputPrefix}/`, '')
+            .replace(`${staticImagePipelineConfig.publicOutputPrefix}`, '');
+        return path.join(root, staticImagePipelineConfig.outputDirectory, outputRelativePath);
+    })));
+}
 function getFallbackExtension(extension) {
     if (extension === '.png') {
         return 'png';
@@ -201,3 +320,6 @@ function getGeneratedExtension(format, fallbackExtension) {
 function toPosixPath(filePath) {
     return filePath.split(path.sep).join('/');
 }
+function toSourcePath(relativePath) {
+    return `${staticImagePipelineConfig.publicSourcePrefix}/${toPosixPath(relativePath)}`;
+}

package/dist/proxy/handle.js

@@ -1,5 +1,5 @@
 import { applyDomActions } from './dom-actions.js';
-import { injectIntoSitemapIndex, rewriteHtml } from './rewrite.js';
+import { injectIntoSitemapIndex, normalizeSitemapPath, removeExcludedUrlsFromSitemap, rewriteHtml } from './rewrite.js';
 /**
  * Create a SvelteKit `Handle` hook that reverse-proxies requests to an origin.
  *
@@ -7,9 +7,13 @@ import { injectIntoSitemapIndex, rewriteHtml } from './rewrite.js';
  * everything else is forwarded to the origin.
  */
 export function createProxyHandle(config) {
+    assertNoDeprecatedSitemapConfig(config);
     const { originUrl, siteUrl } = config;
-    const sitemaps = config.sitemaps ?? [];
-    const sitemapCache = `public, max-age=${config.sitemapCacheSeconds ?? 3600}`;
+    const sitemap = config.sitemap ?? {};
+    const sitemapIndexPath = sitemap.indexPath ? normalizeSitemapPath(sitemap.indexPath) : undefined;
+    const sitemapIncludeFiles = sitemap.includeFiles ?? [];
+    const sitemapExcludePaths = sitemap.excludePaths ?? [];
+    const sitemapCache = `public, max-age=${sitemap.cacheSeconds ?? 3600}`;
     const proxyAssets = config.proxyAssets ?? false;
     const additionalOrigins = config.additionalOrigins ?? [];
     const maxRedirects = config.maxInternalRedirects ?? 5;
@@ -72,8 +76,14 @@ export function createProxyHandle(config) {
             if (contentType.includes('text/xml') || contentType.includes('application/xml')) {
                 let xml = await upstreamResponse.text();
                 xml = xml.replace(/<\?xml-stylesheet[^?]*\?>\s*/g, '');
-                if (sitemaps.length > 0 && xml.includes('</sitemapindex>')) {
-                    xml = injectIntoSitemapIndex(xml, siteUrl, sitemaps);
+                const isConfiguredSitemapIndex = sitemapIndexPath !== undefined && normalizeSitemapPath(pathname) === sitemapIndexPath;
+                if (isConfiguredSitemapIndex &&
+                    sitemapIncludeFiles.length > 0 &&
+                    xml.includes('</sitemapindex>')) {
+                    xml = injectIntoSitemapIndex(xml, siteUrl, sitemapIncludeFiles);
+                }
+                else if (sitemapExcludePaths.length > 0 && xml.includes('</urlset>')) {
+                    xml = removeExcludedUrlsFromSitemap(xml, sitemapExcludePaths);
                 }
                 cleanHeaders.set('cache-control', sitemapCache);
                 return new Response(xml, {
@@ -103,3 +113,11 @@ export function createProxyHandle(config) {
         }
     };
 }
+function assertNoDeprecatedSitemapConfig(config) {
+    if ('sitemaps' in config) {
+        throw new Error('`sitemaps` is deprecated and no longer supported. Use `sitemap.includeFiles` with `sitemap.indexPath` instead.');
+    }
+    if ('sitemapCacheSeconds' in config) {
+        throw new Error('`sitemapCacheSeconds` is deprecated and no longer supported. Use `sitemap.cacheSeconds` instead.');
+    }
+}

package/dist/proxy/index.d.ts

@@ -1,2 +1,2 @@
 export { createProxyHandle } from './handle.js';
-export type { DomAction, ProxyConfig } from './types.js';
+export type { DomAction, ProxyConfig, SitemapConfig } from './types.js';

package/dist/proxy/rewrite.d.ts

@@ -9,5 +9,9 @@
  * - When `proxyAssets` is false, absolute origin URLs are left as-is.
  */
 export declare function rewriteHtml(html: string, originUrl: string, siteUrl: string, proxyAssets?: boolean, additionalOrigins?: string[]): string;
-/** Inject SvelteKit sitemap references into a `<sitemapindex>`. */
-export declare function injectIntoSitemapIndex(xml: string, siteUrl: string, sitemaps: string[]): string;
+/** Normalize URL-like values to comparable sitemap pathnames. */
+export declare function normalizeSitemapPath(value: string): string;
+/** Inject local sitemap references into a configured `<sitemapindex>`. */
+export declare function injectIntoSitemapIndex(xml: string, siteUrl: string, includeFiles: string[]): string;
+/** Remove `<url>` entries whose `<loc>` pathname is listed in `excludePaths`. */
+export declare function removeExcludedUrlsFromSitemap(xml: string, excludePaths: string[]): string;

package/dist/proxy/rewrite.js

@@ -41,10 +41,44 @@ export function rewriteHtml(html, originUrl, siteUrl, proxyAssets = false, addit
     }
     return html;
 }
-/** Inject SvelteKit sitemap references into a `<sitemapindex>`. */
-export function injectIntoSitemapIndex(xml, siteUrl, sitemaps) {
-    const entries = sitemaps
+/** Normalize URL-like values to comparable sitemap pathnames. */
+export function normalizeSitemapPath(value) {
+    let pathname = value.trim();
+    try {
+        pathname = new URL(pathname, 'https://stack-utils.local').pathname;
+    }
+    catch {
+        // Fall back to the raw value below; invalid URL-like values should not crash rewriting.
+    }
+    if (!pathname.startsWith('/')) {
+        pathname = `/${pathname}`;
+    }
+    if (pathname === '/') {
+        return pathname;
+    }
+    return pathname.replace(/\/+$/g, '') || '/';
+}
+/** Inject local sitemap references into a configured `<sitemapindex>`. */
+export function injectIntoSitemapIndex(xml, siteUrl, includeFiles) {
+    if (includeFiles.length === 0) {
+        return xml;
+    }
+    const entries = includeFiles
         .map((url) => `\t<sitemap>\n\t\t<loc>${siteUrl}${url}</loc>\n\t</sitemap>`)
         .join('\n');
     return xml.replace('</sitemapindex>', `${entries}\n</sitemapindex>`);
 }
+/** Remove `<url>` entries whose `<loc>` pathname is listed in `excludePaths`. */
+export function removeExcludedUrlsFromSitemap(xml, excludePaths) {
+    if (excludePaths.length === 0) {
+        return xml;
+    }
+    const excluded = new Set(excludePaths.map(normalizeSitemapPath));
+    return xml.replace(/<url\b[\s\S]*?<\/url>/g, (entry) => {
+        const loc = entry.match(/<loc\b[^>]*>\s*([\s\S]*?)\s*<\/loc>/i)?.[1];
+        if (!loc) {
+            return entry;
+        }
+        return excluded.has(normalizeSitemapPath(loc)) ? '' : entry;
+    });
+}

package/dist/proxy/types.d.ts

@@ -34,22 +34,44 @@ export interface DomAction {
      */
     remove?: boolean;
 }
-/** Configuration for the reverse proxy. */
-export interface ProxyConfig {
-    /** The origin URL (not publicly exposed). */
-    originUrl: string;
-    /** The public site URL (used in sitemaps and link rewriting). */
-    siteUrl: string;
+type DeprecatedProxyOption<Message extends string> = {
+    readonly __deprecatedProxyOption: Message;
+};
+/** Sitemap rewriting configuration for proxied XML responses. */
+export interface SitemapConfig {
+    /**
+     * Origin sitemap index path that can receive `includeFiles`.
+     * Example: `/sitemap_index.xml`.
+     */
+    indexPath?: string;
     /**
-     * SvelteKit sitemap URLs to inject into the origin's sitemap index.
-     * Defaults to `[]`.
+     * Local sitemap files to add to the configured sitemap index.
+     * Example: [`/sveltekit-sitemap.xml`].
      */
-    sitemaps?: string[];
+    includeFiles?: string[];
+    /**
+     * URL paths to remove from origin `<urlset>` sitemap responses.
+     * Matching compares normalized pathnames only.
+     */
+    excludePaths?: string[];
     /**
      * Cache-Control max-age (in seconds) for sitemap responses.
      * Defaults to 3600 (1 hour).
      */
-    sitemapCacheSeconds?: number;
+    cacheSeconds?: number;
+}
+/** Configuration for the reverse proxy. */
+export interface ProxyConfig {
+    /** The origin URL (not publicly exposed). */
+    originUrl: string;
+    /** The public site URL (used in sitemaps and link rewriting). */
+    siteUrl: string;
+    /** Explicit sitemap rewriting configuration for proxied XML responses. */
+    sitemap?: SitemapConfig;
+    /** @deprecated Use `sitemap.includeFiles` with `sitemap.indexPath` instead. */
+    sitemaps?: DeprecatedProxyOption<'`sitemaps` is deprecated. Use `sitemap.includeFiles` with `sitemap.indexPath` instead.'>;
+    /** @deprecated Use `sitemap.cacheSeconds` instead. */
+    sitemapCacheSeconds?: DeprecatedProxyOption<'`sitemapCacheSeconds` is deprecated. Use `sitemap.cacheSeconds` instead.'>;
     /**
      * If true, absolute origin URLs in HTML are rewritten to relative paths
      * so assets are served through the SvelteKit proxy and the origin is never exposed.
@@ -79,3 +101,4 @@ export interface ProxyConfig {
      */
     domActions?: DomAction[];
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@megabudino/stack-utils",
-	"version": "1.4.0",
+	"version": "1.5.0",
 	"description": "Reusable utilities for a SvelteKit stack, including a reverse proxy and static image pipeline",
 	"type": "module",
 	"exports": {
@@ -28,7 +28,7 @@
 	],
 	"scripts": {
 		"build": "node ./scripts/build.mjs",
-		"test": "node --test proxy.test.mjs",
+		"test": "node --test *.test.mjs",
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {