@coralreefventures/site-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coral Reef Ventures, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @coralreefventures/site-tools
+
+Two command-line tools for a Coral Reef public site, which is a Next.js static export served by Amplify Hosting.
+Both sites carried them as `scripts/serve.ts` and `scripts/lighthouse.ts`; they are bins now, and the products' scripts
+go.
+
+```sh
+reef-serve [--root out] [--port 3140]
+reef-lighthouse [--root out] [--reports lighthouse] [--port 3160] [--threshold 90] [--chrome <path>] [path ...]
+```
+
+`reef-serve` serves the export the way Amplify does, for Playwright and Lighthouse: a directory answers with its
+`index.html`, a directory path without its slash redirects to it, anything else is the 404 page with status 404,
+and text is compressed as the CDN compresses it. `PORT` is read when `--port` is not given, so a Playwright
+`webServer` command can pass either:
+
+```ts
+webServer: { command: `pnpm exec reef-serve --port ${port}`, port },
+```
+
+`reef-lighthouse` is the merge gate: Lighthouse on every page in the export's sitemap (or the paths given), with its
+default mobile emulation, each of performance, accessibility, best practices and SEO at the threshold or above. A
+page under it fails the run and leaves its report in `--reports`. Lighthouse itself is not a dependency, because it
+bundles axe-core (MPL-2.0), which is outside the family's licence allowlist; it runs through `pnpm dlx`, pinned
+(`--lighthouse-version`). Chrome is Playwright's Chromium when `@playwright/test` is installed beside this package,
+or `--chrome`.
+
+The library entry exports `serve`, `createStaticServer`, `runLighthouse` and `pagesFromSitemap` for a script that
+wants them in-process.
+
+This is the one package in the repository with a build: a bin has to be JavaScript, because Node refuses to strip
+types from a file under `node_modules`. `tsc` writes `dist/` on `prepack`.

package/dist/bin/reef-lighthouse.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=reef-lighthouse.d.ts.map

package/dist/bin/reef-lighthouse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reef-lighthouse.d.ts","sourceRoot":"","sources":["../../src/bin/reef-lighthouse.ts"],"names":[],"mappings":""}

package/dist/bin/reef-lighthouse.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { runLighthouse } from "../lighthouse.js";
+/**
+ * reef-lighthouse [--root out] [--reports lighthouse] [--port 3160] [--threshold 90] [--chrome <path>] [path ...]
+ *
+ * Lighthouse on every page in the export's sitemap, or the paths given, each category at the threshold or above.
+ * Exits 1 with the failing pages named when one is under, and leaves their reports in --reports.
+ */
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        root: { type: "string", default: "out" },
+        reports: { type: "string", default: "lighthouse" },
+        port: { type: "string", default: "3160" },
+        threshold: { type: "string", default: "90" },
+        chrome: { type: "string" },
+        "lighthouse-version": { type: "string", default: "13.5.0" },
+        help: { type: "boolean", short: "h" },
+    },
+});
+if (values.help) {
+    console.log("reef-lighthouse [--root out] [--reports lighthouse] [--port 3160] [--threshold 90] [--chrome <path>] [path ...]");
+    process.exit(0);
+}
+const threshold = Number(values.threshold) / 100;
+const results = await runLighthouse({
+    root: values.root,
+    reportDir: values.reports,
+    port: Number(values.port),
+    threshold,
+    paths: positionals,
+    lighthouseVersion: values["lighthouse-version"],
+    ...(values.chrome !== undefined && { chrome: values.chrome }),
+});
+const failures = results.filter((result) => result.low.length > 0);
+if (failures.length) {
+    console.error(`Under ${threshold * 100}:\n${failures.map((result) => `${result.path}: ${result.low.join(", ")}`).join("\n")}\nReports in ${values.reports}/`);
+    process.exit(1);
+}
+//# sourceMappingURL=reef-lighthouse.js.map

package/dist/bin/reef-lighthouse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reef-lighthouse.js","sourceRoot":"","sources":["../../src/bin/reef-lighthouse.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;IACxC,gBAAgB,EAAE,IAAI;IACtB,OAAO,EAAE;QACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QACxC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE;QAClD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;QACzC,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE;QAC5C,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC1B,oBAAoB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;QAC3D,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;KACtC;CACF,CAAC,CAAC;AAEH,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;IAChB,OAAO,CAAC,GAAG,CACT,iHAAiH,CAClH,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC;AACjD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC,IAAI;IACjB,SAAS,EAAE,MAAM,CAAC,OAAO;IACzB,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;IACzB,SAAS;IACT,KAAK,EAAE,WAAW;IAClB,iBAAiB,EAAE,MAAM,CAAC,oBAAoB,CAAC;IAC/C,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;CAC9D,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACnE,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,KAAK,CACX,SAAS,SAAS,GAAG,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,OAAO,GAAG,CAC/I,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/bin/reef-serve.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=reef-serve.d.ts.map

package/dist/bin/reef-serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reef-serve.d.ts","sourceRoot":"","sources":["../../src/bin/reef-serve.ts"],"names":[],"mappings":""}

package/dist/bin/reef-serve.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { serve } from "../serve.js";
+/**
+ * reef-serve [--root out] [--port 3140]
+ *
+ * Serves a static export the way Amplify Hosting does, for screen tests and Lighthouse runs. PORT is read when
+ * --port is not given, so a Playwright webServer command can pass either.
+ */
+const { values } = parseArgs({
+    options: {
+        root: { type: "string", default: "out" },
+        port: { type: "string", default: process.env.PORT ?? "3140" },
+        help: { type: "boolean", short: "h" },
+    },
+});
+if (values.help) {
+    console.log("reef-serve [--root out] [--port 3140]");
+    process.exit(0);
+}
+const { url } = await serve({ root: values.root, port: Number(values.port) });
+console.log(`Serving ${values.root} at ${url}`);
+//# sourceMappingURL=reef-serve.js.map

package/dist/bin/reef-serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reef-serve.js","sourceRoot":"","sources":["../../src/bin/reef-serve.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC;;;;;GAKG;AACH,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE;QACP,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QACxC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,MAAM,EAAE;QAC7D,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;KACtC;CACF,CAAC,CAAC;AAEH,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;IACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC9E,OAAO,CAAC,GAAG,CAAC,WAAW,MAAM,CAAC,IAAI,OAAO,GAAG,EAAE,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { type Category, categories, type LighthouseOptions, type PageResult, pagesFromSitemap, reportBase, runLighthouse, } from "./lighthouse.ts";
+export { createStaticServer, encodingFor, type ServeOptions, serve } from "./serve.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EACb,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,gBAAgB,EAChB,UAAU,EACV,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { categories, pagesFromSitemap, reportBase, runLighthouse, } from "./lighthouse.js";
+export { createStaticServer, encodingFor, serve } from "./serve.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EAGV,gBAAgB,EAChB,UAAU,EACV,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAqB,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/lighthouse.d.ts

@@ -0,0 +1,38 @@
+export declare const categories: readonly ["performance", "accessibility", "best-practices", "seo"];
+export type Category = (typeof categories)[number];
+export type LighthouseOptions = {
+    /** The static export; `out` by default. */
+    root?: string;
+    /** Where a failing page's report is left; `lighthouse` by default. */
+    reportDir?: string;
+    /** The port the export is served on for the run. */
+    port?: number;
+    /** The least score, 0 to 1, every category must reach on every page; 0.9 by default. */
+    threshold?: number;
+    /** The pages to audit; every page in the export's sitemap when none are given. */
+    paths?: readonly string[];
+    /** The Lighthouse release `pnpm dlx` runs. */
+    lighthouseVersion?: string;
+    /** The Chrome binary; Playwright's Chromium when it is installed and nothing is given. */
+    chrome?: string;
+    /** Where progress is written. */
+    log?: (line: string) => void;
+};
+export type PageResult = {
+    path: string;
+    /** Each category's score, 0 to 1. */
+    scores: Record<Category, number>;
+    /** The categories under the threshold. */
+    low: Category[];
+};
+/** Every page's path from the export's sitemap, whatever origin the sitemap names. */
+export declare const pagesFromSitemap: (root: string) => Promise<string[]>;
+/** The report file a page's audit is written to: `/` is `home`, `/docs/security/` is `docs-security`. */
+export declare const reportBase: (reportDir: string, pagePath: string) => string;
+/**
+ * The merge gate: Lighthouse on every page, each category at the threshold or above, with Lighthouse's default
+ * mobile emulation and throttling, against the export served as the host serves it. A page under the threshold
+ * keeps its report; a passing page's is removed.
+ */
+export declare const runLighthouse: (options?: LighthouseOptions) => Promise<PageResult[]>;
+//# sourceMappingURL=lighthouse.d.ts.map

package/dist/lighthouse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lighthouse.d.ts","sourceRoot":"","sources":["../src/lighthouse.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,UAAU,oEAAqE,CAAC;AAC7F,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjC,0CAA0C;IAC1C,GAAG,EAAE,QAAQ,EAAE,CAAC;CACjB,CAAC;AAIF,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,MAAM,EAAE,CAGrE,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,UAAU,GAAI,WAAW,MAAM,EAAE,UAAU,MAAM,WACyB,CAAC;AA0CxF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAU,UAAS,iBAAsB,KAAG,OAAO,CAAC,UAAU,EAAE,CAiCzF,CAAC"}

package/dist/lighthouse.js

@@ -0,0 +1,93 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { serve } from "./serve.js";
+export const categories = ["performance", "accessibility", "best-practices", "seo"];
+/** Every page's path from the export's sitemap, whatever origin the sitemap names. */
+export const pagesFromSitemap = async (root) => {
+    const sitemap = await readFile(path.join(root, "sitemap.xml"), "utf8");
+    return [...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)].map((match) => new URL(match[1] ?? "").pathname);
+};
+/** The report file a page's audit is written to: `/` is `home`, `/docs/security/` is `docs-security`. */
+export const reportBase = (reportDir, pagePath) => path.join(reportDir, pagePath.replace(/^\/|\/$/g, "").replaceAll("/", "-") || "home");
+/**
+ * Playwright's Chromium, when the site has Playwright for its screen tests. Resolved at run time rather than
+ * imported, so the tool has no dependency on it.
+ */
+const playwrightChromium = async () => {
+    const specifier = "@playwright/test";
+    try {
+        const playwright = (await import(__rewriteRelativeImportExtension(specifier)));
+        return playwright.chromium.executablePath();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * One Lighthouse run; writes <base>.report.json and <base>.report.html. Lighthouse is not a dependency: it bundles
+ * axe-core (MPL-2.0), which is outside the family's licence allowlist, so its command line runs through `pnpm dlx`,
+ * pinned.
+ */
+const audit = (url, base, version, chrome) => new Promise((resolve, reject) => {
+    const run = spawn("pnpm", [
+        "dlx",
+        `lighthouse@${version}`,
+        url,
+        `--only-categories=${categories.join(",")}`,
+        "--output=json",
+        "--output=html",
+        `--output-path=${base}`,
+        "--chrome-flags=--headless=new --no-sandbox",
+        "--quiet",
+    ], { stdio: ["ignore", "ignore", "inherit"], env: { ...process.env, ...(chrome && { CHROME_PATH: chrome }) } });
+    run.on("error", reject);
+    run.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`Lighthouse exited with ${code} on ${url}`))));
+});
+/**
+ * The merge gate: Lighthouse on every page, each category at the threshold or above, with Lighthouse's default
+ * mobile emulation and throttling, against the export served as the host serves it. A page under the threshold
+ * keeps its report; a passing page's is removed.
+ */
+export const runLighthouse = async (options = {}) => {
+    const root = options.root ?? "out";
+    const reportDir = options.reportDir ?? "lighthouse";
+    const threshold = options.threshold ?? 0.9;
+    const version = options.lighthouseVersion ?? "13.5.0";
+    const log = options.log ?? console.log;
+    const paths = options.paths?.length ? options.paths : await pagesFromSitemap(root);
+    const chrome = options.chrome ?? (await playwrightChromium());
+    const { server, url: origin } = await serve({ root, port: options.port ?? 3160 });
+    const results = [];
+    try {
+        await mkdir(reportDir, { recursive: true });
+        for (const pagePath of paths) {
+            const base = reportBase(reportDir, pagePath);
+            await audit(`${origin}${pagePath}`, base, version, chrome);
+            const report = JSON.parse(await readFile(`${base}.report.json`, "utf8"));
+            const scores = Object.fromEntries(categories.map((category) => [category, report.categories[category]?.score ?? 0]));
+            const low = categories.filter((category) => scores[category] < threshold);
+            results.push({ path: pagePath, scores, low });
+            const shown = categories.map((category) => Math.round(scores[category] * 100)).join("  ");
+            log(`${low.length ? "FAIL" : "ok  "} ${pagePath.padEnd(28)} ${shown}`);
+            if (low.length === 0) {
+                await rm(`${base}.report.json`);
+                await rm(`${base}.report.html`);
+            }
+        }
+    }
+    finally {
+        server.close();
+    }
+    log(`\n${categories.join(", ")}; ${paths.length} pages, threshold ${threshold * 100}`);
+    return results;
+};
+//# sourceMappingURL=lighthouse.js.map

package/dist/lighthouse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lighthouse.js","sourceRoot":"","sources":["../src/lighthouse.ts"],"names":[],"mappings":"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"}

package/dist/serve.d.ts

@@ -0,0 +1,22 @@
+import { type Server } from "node:http";
+/** Brotli or gzip for text, as the browser accepts; images and fonts are already compressed. */
+export declare const encodingFor: (type: string, accepts: string) => "br" | "gzip" | undefined;
+/**
+ * A server for a static export the way Amplify Hosting serves one, for screen tests and Lighthouse runs: a directory
+ * answers with its index.html, a directory path without its slash redirects to it, anything else is the 404 page
+ * with status 404, and text is compressed (Brotli or gzip) as the CDN compresses it. Not started: `listen` it, or
+ * call `serve`.
+ */
+export declare const createStaticServer: (root: string) => Server;
+export type ServeOptions = {
+    /** The static export; `out` by default, Next's. */
+    root?: string;
+    /** 0 takes a free port, which `url` then names. */
+    port?: number;
+};
+/** The server, listening. */
+export declare const serve: ({ root, port, }?: ServeOptions) => Promise<{
+    server: Server;
+    url: string;
+}>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAoBtD,gGAAgG;AAChG,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,IAAI,GAAG,MAAM,GAAG,SAK3E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,MAiCjD,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,6BAA6B;AAC7B,eAAO,MAAM,KAAK,GAAU,kBAGzB,YAAiB,KAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAS7D,CAAC"}

package/dist/serve.js

@@ -0,0 +1,81 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import { createBrotliCompress, createGzip } from "node:zlib";
+const types = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".txt": "text/plain; charset=utf-8",
+    ".xml": "application/xml",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".woff2": "font/woff2",
+    ".ico": "image/x-icon",
+};
+const isFile = async (file) => (await stat(file).catch(() => null))?.isFile() ?? false;
+const isDirectory = async (file) => (await stat(file).catch(() => null))?.isDirectory() ?? false;
+/** Brotli or gzip for text, as the browser accepts; images and fonts are already compressed. */
+export const encodingFor = (type, accepts) => {
+    if (!/^(text\/|application\/(json|xml)|image\/svg)/.test(type)) {
+        return undefined;
+    }
+    return accepts.includes("br") ? "br" : accepts.includes("gzip") ? "gzip" : undefined;
+};
+/**
+ * A server for a static export the way Amplify Hosting serves one, for screen tests and Lighthouse runs: a directory
+ * answers with its index.html, a directory path without its slash redirects to it, anything else is the 404 page
+ * with status 404, and text is compressed (Brotli or gzip) as the CDN compresses it. Not started: `listen` it, or
+ * call `serve`.
+ */
+export const createStaticServer = (root) => {
+    const base = path.resolve(root);
+    return createServer(async (request, response) => {
+        const url = new URL(request.url ?? "/", "http://localhost");
+        const file = path.join(base, decodeURIComponent(url.pathname));
+        if (file !== base && !file.startsWith(`${base}${path.sep}`)) {
+            response.writeHead(400).end();
+            return;
+        }
+        const send = (target, status = 200) => {
+            const type = types[path.extname(target)] ?? "application/octet-stream";
+            const encoding = encodingFor(type, String(request.headers["accept-encoding"] ?? ""));
+            response.writeHead(status, {
+                "Content-Type": type,
+                Vary: "Accept-Encoding",
+                ...(encoding && { "Content-Encoding": encoding }),
+            });
+            const body = createReadStream(target);
+            const compressor = encoding === "br" ? createBrotliCompress() : encoding === "gzip" ? createGzip() : undefined;
+            (compressor ? body.pipe(compressor) : body).pipe(response);
+        };
+        if (await isFile(file)) {
+            send(file);
+        }
+        else if (await isDirectory(file)) {
+            if (url.pathname.endsWith("/")) {
+                send(path.join(file, "index.html"));
+            }
+            else {
+                response.writeHead(301, { Location: `${url.pathname}/${url.search}` }).end();
+            }
+        }
+        else {
+            send(path.join(base, "404.html"), 404);
+        }
+    });
+};
+/** The server, listening. */
+export const serve = async ({ root = "out", port = 3140, } = {}) => {
+    const server = createStaticServer(root);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, () => resolve());
+    });
+    const address = server.address();
+    const bound = typeof address === "object" && address ? address.port : port;
+    return { server, url: `http://localhost:${bound}` };
+};
+//# sourceMappingURL=serve.js.map

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@coralreefventures/site-tools",
+  "version": "0.1.0",
+  "description": "Command-line tools for a Coral Reef public site: serve the static export as the host does, and gate it with Lighthouse.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Coral-Reef-Ventures/reef.git",
+    "directory": "packages/site-tools"
+  },
+  "homepage": "https://coralreefventures.com/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "static-site",
+    "lighthouse",
+    "coral-reef"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "reef-serve": "./dist/bin/reef-serve.js",
+    "reef-lighthouse": "./dist/bin/reef-lighthouse.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@playwright/test": "1.63.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  }
+}

package/src/bin/reef-lighthouse.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+
+import { runLighthouse } from "../lighthouse.ts";
+
+/**
+ * reef-lighthouse [--root out] [--reports lighthouse] [--port 3160] [--threshold 90] [--chrome <path>] [path ...]
+ *
+ * Lighthouse on every page in the export's sitemap, or the paths given, each category at the threshold or above.
+ * Exits 1 with the failing pages named when one is under, and leaves their reports in --reports.
+ */
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    root: { type: "string", default: "out" },
+    reports: { type: "string", default: "lighthouse" },
+    port: { type: "string", default: "3160" },
+    threshold: { type: "string", default: "90" },
+    chrome: { type: "string" },
+    "lighthouse-version": { type: "string", default: "13.5.0" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+
+if (values.help) {
+  console.log(
+    "reef-lighthouse [--root out] [--reports lighthouse] [--port 3160] [--threshold 90] [--chrome <path>] [path ...]",
+  );
+  process.exit(0);
+}
+
+const threshold = Number(values.threshold) / 100;
+const results = await runLighthouse({
+  root: values.root,
+  reportDir: values.reports,
+  port: Number(values.port),
+  threshold,
+  paths: positionals,
+  lighthouseVersion: values["lighthouse-version"],
+  ...(values.chrome !== undefined && { chrome: values.chrome }),
+});
+
+const failures = results.filter((result) => result.low.length > 0);
+if (failures.length) {
+  console.error(
+    `Under ${threshold * 100}:\n${failures.map((result) => `${result.path}: ${result.low.join(", ")}`).join("\n")}\nReports in ${values.reports}/`,
+  );
+  process.exit(1);
+}

package/src/bin/reef-serve.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+
+import { serve } from "../serve.ts";
+
+/**
+ * reef-serve [--root out] [--port 3140]
+ *
+ * Serves a static export the way Amplify Hosting does, for screen tests and Lighthouse runs. PORT is read when
+ * --port is not given, so a Playwright webServer command can pass either.
+ */
+const { values } = parseArgs({
+  options: {
+    root: { type: "string", default: "out" },
+    port: { type: "string", default: process.env.PORT ?? "3140" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+
+if (values.help) {
+  console.log("reef-serve [--root out] [--port 3140]");
+  process.exit(0);
+}
+
+const { url } = await serve({ root: values.root, port: Number(values.port) });
+console.log(`Serving ${values.root} at ${url}`);

package/src/index.ts

@@ -0,0 +1,10 @@
+export {
+  type Category,
+  categories,
+  type LighthouseOptions,
+  type PageResult,
+  pagesFromSitemap,
+  reportBase,
+  runLighthouse,
+} from "./lighthouse.ts";
+export { createStaticServer, encodingFor, type ServeOptions, serve } from "./serve.ts";

package/src/lighthouse.ts

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { serve } from "./serve.ts";
+
+export const categories = ["performance", "accessibility", "best-practices", "seo"] as const;
+export type Category = (typeof categories)[number];
+
+export type LighthouseOptions = {
+  /** The static export; `out` by default. */
+  root?: string;
+  /** Where a failing page's report is left; `lighthouse` by default. */
+  reportDir?: string;
+  /** The port the export is served on for the run. */
+  port?: number;
+  /** The least score, 0 to 1, every category must reach on every page; 0.9 by default. */
+  threshold?: number;
+  /** The pages to audit; every page in the export's sitemap when none are given. */
+  paths?: readonly string[];
+  /** The Lighthouse release `pnpm dlx` runs. */
+  lighthouseVersion?: string;
+  /** The Chrome binary; Playwright's Chromium when it is installed and nothing is given. */
+  chrome?: string;
+  /** Where progress is written. */
+  log?: (line: string) => void;
+};
+
+export type PageResult = {
+  path: string;
+  /** Each category's score, 0 to 1. */
+  scores: Record<Category, number>;
+  /** The categories under the threshold. */
+  low: Category[];
+};
+
+type Report = { categories: Record<string, { score: number | null } | undefined> };
+
+/** Every page's path from the export's sitemap, whatever origin the sitemap names. */
+export const pagesFromSitemap = async (root: string): Promise<string[]> => {
+  const sitemap = await readFile(path.join(root, "sitemap.xml"), "utf8");
+  return [...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)].map((match) => new URL(match[1] ?? "").pathname);
+};
+
+/** The report file a page's audit is written to: `/` is `home`, `/docs/security/` is `docs-security`. */
+export const reportBase = (reportDir: string, pagePath: string) =>
+  path.join(reportDir, pagePath.replace(/^\/|\/$/g, "").replaceAll("/", "-") || "home");
+
+/**
+ * Playwright's Chromium, when the site has Playwright for its screen tests. Resolved at run time rather than
+ * imported, so the tool has no dependency on it.
+ */
+const playwrightChromium = async (): Promise<string | undefined> => {
+  const specifier = "@playwright/test";
+  try {
+    const playwright = (await import(specifier)) as { chromium: { executablePath: () => string } };
+    return playwright.chromium.executablePath();
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * One Lighthouse run; writes <base>.report.json and <base>.report.html. Lighthouse is not a dependency: it bundles
+ * axe-core (MPL-2.0), which is outside the family's licence allowlist, so its command line runs through `pnpm dlx`,
+ * pinned.
+ */
+const audit = (url: string, base: string, version: string, chrome: string | undefined) =>
+  new Promise<void>((resolve, reject) => {
+    const run = spawn(
+      "pnpm",
+      [
+        "dlx",
+        `lighthouse@${version}`,
+        url,
+        `--only-categories=${categories.join(",")}`,
+        "--output=json",
+        "--output=html",
+        `--output-path=${base}`,
+        "--chrome-flags=--headless=new --no-sandbox",
+        "--quiet",
+      ],
+      { stdio: ["ignore", "ignore", "inherit"], env: { ...process.env, ...(chrome && { CHROME_PATH: chrome }) } },
+    );
+    run.on("error", reject);
+    run.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`Lighthouse exited with ${code} on ${url}`))));
+  });
+
+/**
+ * The merge gate: Lighthouse on every page, each category at the threshold or above, with Lighthouse's default
+ * mobile emulation and throttling, against the export served as the host serves it. A page under the threshold
+ * keeps its report; a passing page's is removed.
+ */
+export const runLighthouse = async (options: LighthouseOptions = {}): Promise<PageResult[]> => {
+  const root = options.root ?? "out";
+  const reportDir = options.reportDir ?? "lighthouse";
+  const threshold = options.threshold ?? 0.9;
+  const version = options.lighthouseVersion ?? "13.5.0";
+  const log = options.log ?? console.log;
+  const paths = options.paths?.length ? options.paths : await pagesFromSitemap(root);
+  const chrome = options.chrome ?? (await playwrightChromium());
+  const { server, url: origin } = await serve({ root, port: options.port ?? 3160 });
+  const results: PageResult[] = [];
+  try {
+    await mkdir(reportDir, { recursive: true });
+    for (const pagePath of paths) {
+      const base = reportBase(reportDir, pagePath);
+      await audit(`${origin}${pagePath}`, base, version, chrome);
+      const report = JSON.parse(await readFile(`${base}.report.json`, "utf8")) as Report;
+      const scores = Object.fromEntries(
+        categories.map((category) => [category, report.categories[category]?.score ?? 0]),
+      ) as Record<Category, number>;
+      const low = categories.filter((category) => scores[category] < threshold);
+      results.push({ path: pagePath, scores, low });
+      const shown = categories.map((category) => Math.round(scores[category] * 100)).join("  ");
+      log(`${low.length ? "FAIL" : "ok  "} ${pagePath.padEnd(28)} ${shown}`);
+      if (low.length === 0) {
+        await rm(`${base}.report.json`);
+        await rm(`${base}.report.html`);
+      }
+    }
+  } finally {
+    server.close();
+  }
+  log(`\n${categories.join(", ")}; ${paths.length} pages, threshold ${threshold * 100}`);
+  return results;
+};

package/src/serve.ts

@@ -0,0 +1,92 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import path from "node:path";
+import { createBrotliCompress, createGzip } from "node:zlib";
+
+const types: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".txt": "text/plain; charset=utf-8",
+  ".xml": "application/xml",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".woff2": "font/woff2",
+  ".ico": "image/x-icon",
+};
+
+const isFile = async (file: string) => (await stat(file).catch(() => null))?.isFile() ?? false;
+const isDirectory = async (file: string) => (await stat(file).catch(() => null))?.isDirectory() ?? false;
+
+/** Brotli or gzip for text, as the browser accepts; images and fonts are already compressed. */
+export const encodingFor = (type: string, accepts: string): "br" | "gzip" | undefined => {
+  if (!/^(text\/|application\/(json|xml)|image\/svg)/.test(type)) {
+    return undefined;
+  }
+  return accepts.includes("br") ? "br" : accepts.includes("gzip") ? "gzip" : undefined;
+};
+
+/**
+ * A server for a static export the way Amplify Hosting serves one, for screen tests and Lighthouse runs: a directory
+ * answers with its index.html, a directory path without its slash redirects to it, anything else is the 404 page
+ * with status 404, and text is compressed (Brotli or gzip) as the CDN compresses it. Not started: `listen` it, or
+ * call `serve`.
+ */
+export const createStaticServer = (root: string): Server => {
+  const base = path.resolve(root);
+  return createServer(async (request, response) => {
+    const url = new URL(request.url ?? "/", "http://localhost");
+    const file = path.join(base, decodeURIComponent(url.pathname));
+    if (file !== base && !file.startsWith(`${base}${path.sep}`)) {
+      response.writeHead(400).end();
+      return;
+    }
+    const send = (target: string, status = 200) => {
+      const type = types[path.extname(target)] ?? "application/octet-stream";
+      const encoding = encodingFor(type, String(request.headers["accept-encoding"] ?? ""));
+      response.writeHead(status, {
+        "Content-Type": type,
+        Vary: "Accept-Encoding",
+        ...(encoding && { "Content-Encoding": encoding }),
+      });
+      const body = createReadStream(target);
+      const compressor = encoding === "br" ? createBrotliCompress() : encoding === "gzip" ? createGzip() : undefined;
+      (compressor ? body.pipe(compressor) : body).pipe(response);
+    };
+    if (await isFile(file)) {
+      send(file);
+    } else if (await isDirectory(file)) {
+      if (url.pathname.endsWith("/")) {
+        send(path.join(file, "index.html"));
+      } else {
+        response.writeHead(301, { Location: `${url.pathname}/${url.search}` }).end();
+      }
+    } else {
+      send(path.join(base, "404.html"), 404);
+    }
+  });
+};
+
+export type ServeOptions = {
+  /** The static export; `out` by default, Next's. */
+  root?: string;
+  /** 0 takes a free port, which `url` then names. */
+  port?: number;
+};
+
+/** The server, listening. */
+export const serve = async ({
+  root = "out",
+  port = 3140,
+}: ServeOptions = {}): Promise<{ server: Server; url: string }> => {
+  const server = createStaticServer(root);
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, () => resolve());
+  });
+  const address = server.address();
+  const bound = typeof address === "object" && address ? address.port : port;
+  return { server, url: `http://localhost:${bound}` };
+};