@wells-nelson/build-tools 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# @wells-nelson/build-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build and deployment tooling for SvelteKit PWAs deployed to GitHub Pages.
+
+## CLIs
+
+```json
+"scripts": {
+	"build": "vite build && wn-postbuild --forbid-from seed/demo.json#people.name",
+	"icons": "wn-icons --letters MA --background \"#1f5fa8\"",
+	"manifest": "wn-manifest --name \"My App\" --short-name MA --background \"#f3f5f8\" --theme \"#1f5fa8\" --description \"…\""
+}
+```
+
+- `wn-postbuild`: copies `build/404.html` to `index.html` and writes `.nojekyll`. Optional
+  leak check: `--forbid <text>` or `--forbid-from <file.json>#<path>` fails the build if those
+  strings appear in it (a missing file is skipped, e.g. a git-ignored seed in CI).
+- `wn-icons`: `static/icons/icon-192.png`, `icon-512.png`, `icon-maskable-512.png` and
+  `static/favicon.svg` from one to three letters (A–Z) and colors. No dependencies.
+- `wn-manifest`: `static/manifest.webmanifest`.
+
+The same functions are exported: `postbuild`, `collectStrings`, `writeIcons`, `renderPng`,
+`renderSvg`, `renderManifest`.
+
+## Vite (`@wells-nelson/build-tools/vite`)
+
+```js
+import { basePath, devJsonModule, optimizeDeps } from '@wells-nelson/build-tools/vite';
+
+export default defineConfig(({ mode, command }) => ({
+	plugins: [
+		devJsonModule({ id: 'virtual:seed', file: 'seed/demo.json', enabled: command === 'serve' }),
+		sveltekit({ adapter: adapter({ fallback: '404.html' }), paths: { base: basePath({ mode, env: loadEnv(mode, process.cwd(), ''), fallback: '/my-app' }) } })
+	],
+	optimizeDeps: optimizeDeps(['some-lazily-loaded-dep'])
+}));
+```
+
+## Service worker (`@wells-nelson/build-tools/service-worker`)
+
+```ts
+/// <reference types="@sveltejs/kit" />
+import { version } from '$app/env';
+import { assets, immutable } from '$app/manifest';
+import { self } from '$app/service-worker';
+import { registerAppShellCache } from '@wells-nelson/build-tools/service-worker';
+
+registerAppShellCache({ sw: self, version, files: [...immutable, ...assets], cachePrefix: 'my-app' });
+```
+
+## Templates
+
+`templates/deploy-pages.yml` (replace `__REPO__`) and `templates/manifest.webmanifest`.
+
+Try the icons, manifest, `basePath` and `postbuild` in the sandbox's Build tools page.

package/dist/cli/icons.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/icons.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * wn-icons --letters WN --background "#1f5fa8" [--foreground "#ffffff"] [--out static]
+ *
+ * Writes the PWA icons and favicon; commit the output under static/.
+ */
+import { parseArgs } from 'node:util';
+import { writeIcons } from '../icons.js';
+const { values } = parseArgs({
+    options: {
+        letters: { type: 'string' },
+        background: { type: 'string' },
+        foreground: { type: 'string', default: '#ffffff' },
+        out: { type: 'string', default: 'static' }
+    }
+});
+if (!values.letters || !values.background) {
+    console.error('Usage: wn-icons --letters WN --background "#1f5fa8" [--foreground "#ffffff"] [--out static]');
+    process.exit(1);
+}
+try {
+    const files = writeIcons({
+        letters: values.letters,
+        background: values.background,
+        foreground: values.foreground,
+        outDir: values.out
+    });
+    console.log(`icons written: ${files.join(', ')}`);
+}
+catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+}

package/dist/cli/manifest.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/manifest.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * wn-manifest --name "My App" --short-name MA --description "…"
+ *             --background "#f3f5f8" --theme "#1f5fa8" [--out static/manifest.webmanifest]
+ */
+import { writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { renderManifest } from '../manifest.js';
+const { values } = parseArgs({
+    options: {
+        name: { type: 'string' },
+        'short-name': { type: 'string' },
+        description: { type: 'string', default: '' },
+        background: { type: 'string' },
+        theme: { type: 'string' },
+        out: { type: 'string', default: 'static/manifest.webmanifest' }
+    }
+});
+const { name, 'short-name': shortName, background, theme } = values;
+if (!name || !shortName || !background || !theme) {
+    console.error('Usage: wn-manifest --name <name> --short-name <short> --background <#hex> --theme <#hex> [--description <text>] [--out <path>]');
+    process.exit(1);
+}
+writeFileSync(values.out, renderManifest({ name, shortName, description: values.description, backgroundColor: background, themeColor: theme }));
+console.log(`manifest written: ${values.out}`);

package/dist/cli/postbuild.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/postbuild.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * wn-postbuild [--dir build] [--shell 404.html] [--forbid <text>]... [--forbid-from <file.json>#<path>]...
+ *
+ * Example: wn-postbuild --forbid-from seed/demo.json#people.name
+ * A missing --forbid-from file is skipped (the seed is git-ignored, so CI doesn't have it).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { collectStrings, postbuild } from '../postbuild.js';
+const { values } = parseArgs({
+    options: {
+        dir: { type: 'string', default: 'build' },
+        shell: { type: 'string', default: '404.html' },
+        forbid: { type: 'string', multiple: true, default: [] },
+        'forbid-from': { type: 'string', multiple: true, default: [] }
+    }
+});
+const forbid = [...values.forbid];
+for (const spec of values['forbid-from']) {
+    const [file, path = ''] = spec.split('#');
+    if (!existsSync(file))
+        continue;
+    forbid.push(...collectStrings(JSON.parse(readFileSync(file, 'utf8')), path));
+}
+try {
+    postbuild({ dir: values.dir, shell: values.shell, forbid });
+}
+catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+}

package/dist/icons.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PWA icons (PNG) and favicon (SVG) drawn from one to three letters, without dependencies.
+ * Letters are polylines with round caps in a 100x100 design space (y down), 50 units tall.
+ */
+type Point = [number, number];
+type Path = Point[];
+export declare const SUPPORTED_LETTERS: string;
+/** The mark's strokes in the 100x100 design space. */
+export declare function markPaths(letters: string): Path[];
+export declare function parseHex(hex: string): [number, number, number];
+export interface IconOptions {
+    /** One to three letters, e.g. "WN". */
+    letters: string;
+    /** Background color, #rrggbb. */
+    background: string;
+    /** Letter color, #rrggbb (default white). */
+    foreground?: string;
+}
+/** Render the mark as a PNG. Maskable icons are full-bleed with the mark inside the safe zone. */
+export declare function renderPng(size: number, { letters, background, foreground }: IconOptions, { maskable }?: {
+    maskable?: boolean | undefined;
+}): Buffer<ArrayBuffer>;
+/** The favicon: the same mark as an SVG with a rounded background. */
+export declare function renderSvg({ letters, background, foreground }: IconOptions): string;
+/**
+ * Write `icons/icon-192.png`, `icons/icon-512.png`, `icons/icon-maskable-512.png` and
+ * `favicon.svg` under `outDir` (SvelteKit's `static/`). Returns the written paths.
+ */
+export declare function writeIcons(options: IconOptions & {
+    outDir?: string;
+}): string[];
+export {};

package/dist/icons.js

@@ -0,0 +1,197 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { deflateSync } from 'node:zlib';
+const STROKE = 11;
+/** Points along an ellipse from angle a0 to a1 (degrees, y down: -90 is up). */
+function arc(cx, cy, rx, ry, a0, a1, step = 5) {
+    const pts = [];
+    const dir = a1 >= a0 ? 1 : -1;
+    for (let a = a0; dir > 0 ? a <= a1 : a >= a1; a += dir * step) {
+        const t = (a * Math.PI) / 180;
+        pts.push([cx + rx * Math.cos(t), cy + ry * Math.sin(t)]);
+    }
+    return pts;
+}
+const P = (...pts) => pts;
+/** Glyphs centered on x = 0, from y = 0 (top) to y = 50 (baseline), about 21 units wide. */
+const GLYPHS = {
+    A: [P([-10, 50], [0, 0], [10, 50]), P([-5.6, 30], [5.6, 30])],
+    B: [
+        [[-9, 50], [-9, 0], [-1, 0], ...arc(-1, 11.5, 11.5, 11.5, -90, 90), [-9, 23]],
+        [[-9, 23], [-3.5, 23], ...arc(-3.5, 36.5, 13.5, 13.5, -90, 90), [-9, 50]]
+    ],
+    C: [arc(0, 25, 10.5, 25, -45, -315)],
+    D: [[[-9, 0], [-9, 50]], [[-9, 0], ...arc(-9, 25, 19.5, 25, -90, 90)]],
+    E: [P([10, 0], [-9, 0], [-9, 50], [10, 50]), P([-9, 25], [6, 25])],
+    F: [P([10, 0], [-9, 0], [-9, 50]), P([-9, 25], [6, 25])],
+    G: [[...arc(0, 25, 10.5, 25, -45, -360), [2, 25]]],
+    H: [P([-10, 0], [-10, 50]), P([10, 0], [10, 50]), P([-10, 25], [10, 25])],
+    I: [P([0, 0], [0, 50]), P([-6, 0], [6, 0]), P([-6, 50], [6, 50])],
+    J: [[[8, 0], [8, 38], ...arc(-1, 38, 9, 12, 0, 160)]],
+    K: [P([-9, 0], [-9, 50]), P([10, 0], [-9, 30]), P([-2.5, 22], [10, 50])],
+    L: [P([-10, 0], [-10, 50], [10, 50])],
+    M: [P([-11, 50], [-11, 0], [0, 30], [11, 0], [11, 50])],
+    N: [P([-10, 50], [-10, 0], [10, 50], [10, 0])],
+    O: [arc(0, 25, 10.5, 25, 0, 360)],
+    P: [[[-9, 50], [-9, 0], [0, 0], ...arc(0, 13.5, 10, 13.5, -90, 90), [-9, 27]]],
+    Q: [arc(0, 25, 10.5, 25, 0, 360), P([3, 38], [11, 52])],
+    R: [[[-9, 50], [-9, 0], [0, 0], ...arc(0, 13.5, 10, 13.5, -90, 90), [-9, 27]], P([0, 27], [10, 50])],
+    S: [[...arc(0, 12.5, 12.5, 12.5, -20, -270), ...arc(0, 37.5, 12.5, 12.5, -90, 160)]],
+    T: [P([-11, 0], [11, 0]), P([0, 0], [0, 50])],
+    U: [[[-10, 0], ...arc(0, 40, 10, 10, 180, 0), [10, 0]]],
+    V: [P([-10, 0], [0, 50], [10, 0])],
+    W: [P([-12, 0], [-6, 50], [0, 18], [6, 50], [12, 0])],
+    X: [P([-10, 0], [10, 50]), P([10, 0], [-10, 50])],
+    Y: [P([-10, 0], [0, 25], [10, 0]), P([0, 25], [0, 50])],
+    Z: [P([-10, 0], [10, 0], [-10, 50], [10, 50])]
+};
+export const SUPPORTED_LETTERS = Object.keys(GLYPHS).join('');
+/** Horizontal centers of each letter for a mark of 1, 2 or 3 letters. */
+const SLOTS = { 1: [50], 2: [32, 68], 3: [21, 50, 79] };
+/** The mark's strokes in the 100x100 design space. */
+export function markPaths(letters) {
+    const chars = [...letters.toUpperCase()];
+    const slots = SLOTS[chars.length];
+    if (!slots)
+        throw new Error(`Icons need 1 to 3 letters, got "${letters}".`);
+    return chars.flatMap((ch, i) => {
+        const glyph = GLYPHS[ch];
+        if (!glyph)
+            throw new Error(`No glyph for "${ch}". Supported: ${SUPPORTED_LETTERS}.`);
+        return glyph.map((path) => path.map(([x, y]) => [slots[i] + x, 25 + y]));
+    });
+}
+export function parseHex(hex) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        throw new Error(`Expected a #rrggbb color, got "${hex}".`);
+    const n = parseInt(m[1], 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+}
+function distToSegment(px, py, [ax, ay], [bx, by]) {
+    const dx = bx - ax;
+    const dy = by - ay;
+    const len2 = dx * dx + dy * dy;
+    const t = len2 ? Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / len2)) : 0;
+    return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+}
+function distToGlyph(paths, x, y) {
+    let min = Infinity;
+    for (const path of paths) {
+        for (let i = 0; i < path.length - 1; i++)
+            min = Math.min(min, distToSegment(x, y, path[i], path[i + 1]));
+    }
+    return min;
+}
+function inRoundedRect(x, y, size, radius) {
+    const cx = Math.min(Math.max(x, radius), size - radius);
+    const cy = Math.min(Math.max(y, radius), size - radius);
+    return Math.hypot(x - cx, y - cy) <= radius;
+}
+/** Render the mark as a PNG. Maskable icons are full-bleed with the mark inside the safe zone. */
+export function renderPng(size, { letters, background, foreground = '#ffffff' }, { maskable = false } = {}) {
+    const paths = markPaths(letters);
+    const BG = parseHex(background);
+    const FG = parseHex(foreground);
+    const SS = 4; // supersampling per axis
+    const glyphScale = maskable ? 0.62 : 0.82;
+    const offset = (1 - glyphScale) * 50;
+    const radius = maskable ? 0 : size * 0.22;
+    const toGlyph = (v) => ((v / size) * 100 - offset) / glyphScale;
+    // Half a pixel's diagonal in design units: pixels further than this from the stroke edge are
+    // entirely inside or outside it, so only edge pixels need supersampling.
+    const halfDiagonal = (Math.SQRT2 / 2) * (100 / size / glyphScale);
+    const px = Buffer.alloc(size * size * 4);
+    for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; x++) {
+            const d = distToGlyph(paths, toGlyph(x + 0.5), toGlyph(y + 0.5));
+            const coverage = d > STROKE / 2 + halfDiagonal ? 0 : d < STROKE / 2 - halfDiagonal ? 1 : -1;
+            let bg = 0;
+            let fg = 0;
+            for (let sy = 0; sy < SS; sy++) {
+                for (let sx = 0; sx < SS; sx++) {
+                    const fx = x + (sx + 0.5) / SS;
+                    const fy = y + (sy + 0.5) / SS;
+                    if (!maskable && !inRoundedRect(fx, fy, size, radius))
+                        continue;
+                    bg++;
+                    if (coverage === 1 || (coverage === -1 && distToGlyph(paths, toGlyph(fx), toGlyph(fy)) <= STROKE / 2))
+                        fg++;
+                }
+            }
+            const i = (y * size + x) * 4;
+            const f = bg ? fg / bg : 0;
+            for (let c = 0; c < 3; c++)
+                px[i + c] = Math.round(BG[c] * (1 - f) + FG[c] * f);
+            px[i + 3] = Math.round((bg / (SS * SS)) * 255);
+        }
+    }
+    return encodePng(size, size, px);
+}
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++)
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+});
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (const b of buf)
+        c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length);
+    const td = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(td));
+    return Buffer.concat([len, td, crc]);
+}
+function encodePng(w, h, rgba) {
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(w, 0);
+    ihdr.writeUInt32BE(h, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 6; // RGBA
+    const raw = Buffer.alloc((w * 4 + 1) * h);
+    for (let y = 0; y < h; y++)
+        rgba.copy(raw, y * (w * 4 + 1) + 1, y * w * 4, (y + 1) * w * 4);
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        chunk('IHDR', ihdr),
+        chunk('IDAT', deflateSync(raw, { level: 9 })),
+        chunk('IEND', Buffer.alloc(0))
+    ]);
+}
+/** The favicon: the same mark as an SVG with a rounded background. */
+export function renderSvg({ letters, background, foreground = '#ffffff' }) {
+    const s = 0.82;
+    const o = (1 - s) * 50;
+    const pt = ([x, y]) => `${(o + x * s).toFixed(2)} ${(o + y * s).toFixed(2)}`;
+    const paths = markPaths(letters).map((p) => `<path d="M${p.map(pt).join(' L')}"/>`);
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+<rect width="100" height="100" rx="22" fill="${background}"/>
+<g fill="none" stroke="${foreground}" stroke-width="${(STROKE * s).toFixed(2)}" stroke-linecap="round" stroke-linejoin="round">
+${paths.join('\n')}
+</g>
+</svg>
+`;
+}
+/**
+ * Write `icons/icon-192.png`, `icons/icon-512.png`, `icons/icon-maskable-512.png` and
+ * `favicon.svg` under `outDir` (SvelteKit's `static/`). Returns the written paths.
+ */
+export function writeIcons(options) {
+    const outDir = options.outDir ?? 'static';
+    mkdirSync(join(outDir, 'icons'), { recursive: true });
+    const files = [
+        [join(outDir, 'icons/icon-192.png'), renderPng(192, options)],
+        [join(outDir, 'icons/icon-512.png'), renderPng(512, options)],
+        [join(outDir, 'icons/icon-maskable-512.png'), renderPng(512, options, { maskable: true })],
+        [join(outDir, 'favicon.svg'), renderSvg(options)]
+    ];
+    for (const [path, data] of files)
+        writeFileSync(path, data);
+    return files.map(([path]) => path);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SUPPORTED_LETTERS, markPaths, parseHex, renderPng, renderSvg, writeIcons, type IconOptions } from './icons.js';
+export { renderManifest, type ManifestOptions } from './manifest.js';
+export { collectStrings, postbuild, type PostbuildOptions } from './postbuild.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { SUPPORTED_LETTERS, markPaths, parseHex, renderPng, renderSvg, writeIcons } from './icons.js';
+export { renderManifest } from './manifest.js';
+export { collectStrings, postbuild } from './postbuild.js';

package/dist/manifest.d.ts

@@ -0,0 +1,16 @@
+export interface ManifestOptions {
+    /** e.g. "My App — Projects" */
+    name: string;
+    /** e.g. "MA" */
+    shortName: string;
+    description: string;
+    /** Splash background, usually the theme's --bg. */
+    backgroundColor: string;
+    /** Browser UI color, usually the theme's --accent. */
+    themeColor: string;
+}
+/**
+ * `static/manifest.webmanifest` for an installable PWA served from any base path (relative
+ * start_url and scope), using the icons `writeIcons` produces.
+ */
+export declare function renderManifest(o: ManifestOptions): string;

package/dist/manifest.js

@@ -0,0 +1,23 @@
+/**
+ * `static/manifest.webmanifest` for an installable PWA served from any base path (relative
+ * start_url and scope), using the icons `writeIcons` produces.
+ */
+export function renderManifest(o) {
+    const manifest = {
+        name: o.name,
+        short_name: o.shortName,
+        description: o.description,
+        start_url: './',
+        scope: './',
+        display: 'standalone',
+        background_color: o.backgroundColor,
+        theme_color: o.themeColor,
+        icons: [
+            { src: 'icons/icon-192.png', sizes: '192x192', type: 'image/png' },
+            { src: 'icons/icon-512.png', sizes: '512x512', type: 'image/png' },
+            { src: 'icons/icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+            { src: 'favicon.svg', sizes: 'any', type: 'image/svg+xml' }
+        ]
+    };
+    return `${JSON.stringify(manifest, null, '\t')}\n`;
+}

package/dist/postbuild.d.ts

@@ -0,0 +1,26 @@
+export interface PostbuildOptions {
+    /** adapter-static output directory. */
+    dir?: string;
+    /** The SPA shell adapter-static writes (its `fallback`). */
+    shell?: string;
+    /**
+     * Strings that must never appear in the build, e.g. names from dev-only seed data. The build
+     * fails if any text file contains one.
+     */
+    forbid?: string[];
+    log?: (message: string) => void;
+}
+/**
+ * GitHub Pages fixups for a SvelteKit adapter-static build:
+ * - copy the SPA shell (404.html, which Pages serves for every unknown path) to index.html, so
+ *   the root URL and the service worker's offline shell exist too;
+ * - write .nojekyll so Pages' Jekyll doesn't hide the _app directory;
+ * - optionally check that forbidden strings (e.g. dev seed data) didn't leak into the build.
+ */
+export declare function postbuild({ dir, shell, forbid, log }?: PostbuildOptions): void;
+/**
+ * Collect strings from a JSON value along a dotted path, walking through arrays, e.g.
+ * `collectStrings(seed, 'people.name')`. Strings shorter than `minLength` are skipped so
+ * common short words don't cause false alarms.
+ */
+export declare function collectStrings(value: unknown, path: string, minLength?: number): string[];

package/dist/postbuild.js

@@ -0,0 +1,55 @@
+import { copyFileSync, existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const TEXT_FILE = /\.(js|html|json|css|webmanifest|txt|xml|svg)$/;
+/**
+ * GitHub Pages fixups for a SvelteKit adapter-static build:
+ * - copy the SPA shell (404.html, which Pages serves for every unknown path) to index.html, so
+ *   the root URL and the service worker's offline shell exist too;
+ * - write .nojekyll so Pages' Jekyll doesn't hide the _app directory;
+ * - optionally check that forbidden strings (e.g. dev seed data) didn't leak into the build.
+ */
+export function postbuild({ dir = 'build', shell = '404.html', forbid = [], log = console.log } = {}) {
+    const shellPath = join(dir, shell);
+    if (!existsSync(shellPath))
+        throw new Error(`${shellPath} not found; did the build run?`);
+    copyFileSync(shellPath, join(dir, 'index.html'));
+    writeFileSync(join(dir, '.nojekyll'), '');
+    log(`postbuild: wrote ${join(dir, 'index.html')} and ${join(dir, '.nojekyll')}`);
+    const needles = forbid.filter(Boolean);
+    if (needles.length === 0)
+        return;
+    const files = [];
+    const walk = (d) => {
+        for (const name of readdirSync(d)) {
+            const path = join(d, name);
+            if (statSync(path).isDirectory())
+                walk(path);
+            else if (TEXT_FILE.test(name))
+                files.push(path);
+        }
+    };
+    walk(dir);
+    for (const file of files) {
+        const text = readFileSync(file, 'utf8');
+        const hit = needles.find((n) => text.includes(n));
+        if (hit !== undefined)
+            throw new Error(`postbuild: forbidden content found in ${file}. It must never be deployed.`);
+    }
+    log(`postbuild: checked ${files.length} files, no forbidden content in the build`);
+}
+/**
+ * Collect strings from a JSON value along a dotted path, walking through arrays, e.g.
+ * `collectStrings(seed, 'people.name')`. Strings shorter than `minLength` are skipped so
+ * common short words don't cause false alarms.
+ */
+export function collectStrings(value, path, minLength = 4) {
+    let current = [value];
+    for (const key of path.split('.').filter(Boolean)) {
+        current = current
+            .flatMap((v) => (Array.isArray(v) ? v : [v]))
+            .map((v) => (v && typeof v === 'object' ? v[key] : undefined));
+    }
+    return current
+        .flatMap((v) => (Array.isArray(v) ? v : [v]))
+        .filter((v) => typeof v === 'string' && v.length >= minLength);
+}

package/dist/service-worker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Offline-first app shell for a SvelteKit service worker. Everything the app needs is precached
+ * on install; navigations fall back to the cached shell (the app root) when the network is
+ * unavailable; cross-origin requests (Supabase, Google avatars) are left to the network.
+ *
+ * ```ts
+ * // src/service-worker/index.ts
+ * /// <reference types="@sveltejs/kit" />
+ * import { version } from '$app/env';
+ * import { assets, immutable } from '$app/manifest';
+ * import { self } from '$app/service-worker';
+ * import { registerAppShellCache } from '@wells-nelson/build-tools/service-worker';
+ *
+ * registerAppShellCache({ sw: self, version, files: [...immutable, ...assets], cachePrefix: 'my-app' });
+ * ```
+ */
+/** The parts of ServiceWorkerGlobalScope this uses (so it type-checks without the WebWorker lib). */
+export interface ServiceWorkerScopeLike {
+    registration: {
+        scope: string;
+    };
+    clients: {
+        claim(): Promise<void>;
+    };
+    skipWaiting(): Promise<void>;
+    addEventListener(type: string, listener: (event: any) => void): void;
+}
+export interface AppShellCacheOptions {
+    sw: ServiceWorkerScopeLike;
+    /** Build version; each deploy gets a fresh cache and old ones are deleted. */
+    version: string;
+    /** Files to precache, relative to the scope (SvelteKit's `immutable` and `assets`). */
+    files: Array<string | {
+        path: string;
+    }>;
+    /** Cache name prefix (default 'app'). */
+    cachePrefix?: string;
+}
+export declare function registerAppShellCache({ sw, version, files, cachePrefix }: AppShellCacheOptions): {
+    cacheName: string;
+    precache: string[];
+};

package/dist/service-worker.js

@@ -0,0 +1,73 @@
+/**
+ * Offline-first app shell for a SvelteKit service worker. Everything the app needs is precached
+ * on install; navigations fall back to the cached shell (the app root) when the network is
+ * unavailable; cross-origin requests (Supabase, Google avatars) are left to the network.
+ *
+ * ```ts
+ * // src/service-worker/index.ts
+ * /// <reference types="@sveltejs/kit" />
+ * import { version } from '$app/env';
+ * import { assets, immutable } from '$app/manifest';
+ * import { self } from '$app/service-worker';
+ * import { registerAppShellCache } from '@wells-nelson/build-tools/service-worker';
+ *
+ * registerAppShellCache({ sw: self, version, files: [...immutable, ...assets], cachePrefix: 'my-app' });
+ * ```
+ */
+export function registerAppShellCache({ sw, version, files, cachePrefix = 'app' }) {
+    const CACHE = `${cachePrefix}-cache-${version}`;
+    const scope = new URL(sw.registration.scope);
+    // The app root serves the SPA shell (index.html on GitHub Pages, the fallback page elsewhere).
+    const SHELL = scope.href;
+    const PRECACHE = files.map((f) => new URL(typeof f === 'string' ? f : f.path, scope).href).concat(SHELL);
+    sw.addEventListener('install', (event) => {
+        event.waitUntil((async () => {
+            const cache = await caches.open(CACHE);
+            await cache.addAll(PRECACHE);
+            await sw.skipWaiting();
+        })());
+    });
+    sw.addEventListener('activate', (event) => {
+        event.waitUntil((async () => {
+            for (const key of await caches.keys())
+                if (key !== CACHE)
+                    await caches.delete(key);
+            await sw.clients.claim();
+        })());
+    });
+    sw.addEventListener('fetch', (event) => {
+        const { request } = event;
+        if (request.method !== 'GET')
+            return;
+        const url = new URL(request.url);
+        if (url.origin !== scope.origin)
+            return;
+        if (request.mode === 'navigate') {
+            event.respondWith((async () => {
+                try {
+                    const response = await fetch(request);
+                    // GitHub Pages serves the SPA shell as 404.html with a 404 status for deep links.
+                    if (response.ok || response.status === 404)
+                        return response;
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                catch {
+                    const cached = await caches.match(SHELL);
+                    return cached ?? Response.error();
+                }
+            })());
+            return;
+        }
+        event.respondWith((async () => {
+            const cache = await caches.open(CACHE);
+            const cached = await cache.match(request);
+            if (cached)
+                return cached;
+            const response = await fetch(request);
+            if (response.ok && url.pathname.startsWith(scope.pathname))
+                cache.put(request, response.clone());
+            return response;
+        })());
+    });
+    return { cacheName: CACHE, precache: PRECACHE };
+}

package/dist/vite.d.ts

@@ -0,0 +1,35 @@
+import type { Plugin } from 'vite';
+/**
+ * SvelteKit `paths.base` from the BASE_PATH env var: the one place the deploy path is configured.
+ * GitHub project pages are served from /<repo-name> (the `fallback`); set BASE_PATH to "/" for
+ * a custom domain. Development always serves from the root.
+ */
+export declare function basePath({ mode, env, fallback }: {
+    mode: string;
+    env: Record<string, string | undefined>;
+    /** e.g. '/my-app' */
+    fallback: string;
+}): '' | `/${string}`;
+/**
+ * Runtime dependencies of `@wells-nelson/data-storage`. Pre-bundle them when the dev server
+ * starts; otherwise Vite discovers some mid-session, re-bundles, and the already-loaded modules
+ * break ("Cannot read properties of undefined (reading 'call')" / a 500 page) until a full reload.
+ */
+export declare const SHARED_OPTIMIZE_DEPS: string[];
+/** `optimizeDeps` with the shared list plus the app's own lazily loaded deps (e.g. a search library). */
+export declare function optimizeDeps(extra?: string[]): {
+    include: string[];
+};
+/**
+ * Serve a git-ignored JSON file (e.g. seed data with real names) as a virtual module to the dev
+ * server only. Builds always get `null`, so the data can never be bundled or deployed.
+ *
+ * ```js
+ * plugins: [devJsonModule({ id: 'virtual:seed', file: 'seed/demo.json', enabled: command === 'serve' }), sveltekit()]
+ * ```
+ */
+export declare function devJsonModule({ id, file, enabled }: {
+    id: string;
+    file: string;
+    enabled: boolean;
+}): Plugin;

package/dist/vite.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * SvelteKit `paths.base` from the BASE_PATH env var: the one place the deploy path is configured.
+ * GitHub project pages are served from /<repo-name> (the `fallback`); set BASE_PATH to "/" for
+ * a custom domain. Development always serves from the root.
+ */
+export function basePath({ mode, env, fallback }) {
+    const raw = mode === 'development' ? '/' : env.BASE_PATH || fallback;
+    return raw === '/' ? '' : `/${raw.replace(/^\/+|\/+$/g, '')}`;
+}
+/**
+ * Runtime dependencies of `@wells-nelson/data-storage`. Pre-bundle them when the dev server
+ * starts; otherwise Vite discovers some mid-session, re-bundles, and the already-loaded modules
+ * break ("Cannot read properties of undefined (reading 'call')" / a 500 page) until a full reload.
+ */
+export const SHARED_OPTIMIZE_DEPS = [
+    '@supabase/supabase-js',
+    '@tanstack/db',
+    '@tanstack/rxdb-db-collection',
+    '@tanstack/svelte-db',
+    'rxdb/plugins/core',
+    'rxdb/plugins/replication-supabase',
+    'rxdb/plugins/storage-dexie'
+];
+/** `optimizeDeps` with the shared list plus the app's own lazily loaded deps (e.g. a search library). */
+export function optimizeDeps(extra = []) {
+    return { include: [...extra, ...SHARED_OPTIMIZE_DEPS] };
+}
+/**
+ * Serve a git-ignored JSON file (e.g. seed data with real names) as a virtual module to the dev
+ * server only. Builds always get `null`, so the data can never be bundled or deployed.
+ *
+ * ```js
+ * plugins: [devJsonModule({ id: 'virtual:seed', file: 'seed/demo.json', enabled: command === 'serve' }), sveltekit()]
+ * ```
+ */
+export function devJsonModule({ id, file, enabled }) {
+    const path = resolve(file);
+    const resolved = `\0${id}`;
+    return {
+        name: `dev-json:${id}`,
+        resolveId: (source) => (source === id ? resolved : undefined),
+        load(source) {
+            if (source !== resolved)
+                return;
+            if (!enabled || !existsSync(path))
+                return 'export default null;';
+            this.addWatchFile(path);
+            return `export default ${readFileSync(path, 'utf8')};`;
+        }
+    };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@wells-nelson/build-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Build and deployment tooling for Wells Nelson SvelteKit PWAs: postbuild, PWA icon generator, Vite config pieces, service worker, and templates.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bnelson729/wells-nelson-components.git",
+    "directory": "src/npm/build-tools"
+  },
+  "homepage": "https://github.com/bnelson729/wells-nelson-components/tree/main/src/npm/build-tools#readme",
+  "bugs": {
+    "url": "https://github.com/bnelson729/wells-nelson-components/issues"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./service-worker": {
+      "types": "./dist/service-worker.d.ts",
+      "default": "./dist/service-worker.js"
+    },
+    "./templates/*": "./templates/*"
+  },
+  "bin": {
+    "wn-postbuild": "./dist/cli/postbuild.js",
+    "wn-icons": "./dist/cli/icons.js",
+    "wn-manifest": "./dist/cli/manifest.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint:package": "publint"
+  },
+  "peerDependencies": {
+    "vite": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/templates/deploy-pages.yml

@@ -0,0 +1,49 @@
+# GitHub Pages deploy for a SvelteKit adapter-static app.
+# Copy to .github/workflows/deploy.yml and replace __REPO__ with the repository name.
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+        env:
+          # Repository variables (Settings > Secrets and variables > Actions > Variables).
+          # Leave the Supabase ones unset to deploy a local-only build.
+          VITE_SUPABASE_URL: ${{ vars.SUPABASE_URL }}
+          VITE_SUPABASE_ANON_KEY: ${{ vars.SUPABASE_ANON_KEY }}
+          # "/__REPO__" for <user>.github.io/__REPO__; set BASE_PATH to "/" for a custom domain.
+          BASE_PATH: ${{ vars.BASE_PATH || '/__REPO__' }}
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/templates/manifest.webmanifest

@@ -0,0 +1,16 @@
+{
+	"name": "__NAME__",
+	"short_name": "__SHORT_NAME__",
+	"description": "__DESCRIPTION__",
+	"start_url": "./",
+	"scope": "./",
+	"display": "standalone",
+	"background_color": "#f3f5f8",
+	"theme_color": "#1f5fa8",
+	"icons": [
+		{ "src": "icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
+		{ "src": "icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
+		{ "src": "icons/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" },
+		{ "src": "favicon.svg", "sizes": "any", "type": "image/svg+xml" }
+	]
+}