@nurkamol/seo-audit 1.34.0 → 1.35.0

package/README.md

@@ -14,6 +14,8 @@
 <p align="center">
   <a href="https://github.com/marketplace/actions/full-site-seo-audit"><img src="https://img.shields.io/badge/GitHub%20Marketplace-Full--site%20SEO%20Audit-f97316?logo=github&logoColor=white" alt="GitHub Marketplace"></a>
   <a href="https://github.com/nurkamol/seo-audit/actions/workflows/test.yml"><img src="https://github.com/nurkamol/seo-audit/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+  <a href="https://github.com/nurkamol/seo-audit/releases/latest"><img src="https://img.shields.io/badge/Download-macOS%20app-0a0a0a?logo=apple&logoColor=white" alt="Download the macOS app"></a>
+  <a href="https://www.npmjs.com/package/@nurkamol/seo-audit"><img src="https://img.shields.io/npm/v/@nurkamol/seo-audit?color=cb3837&logo=npm&logoColor=white&label=npm" alt="npm"></a>
   <a href="https://github.com/nurkamol/seo-audit/releases"><img src="https://img.shields.io/github/v/release/nurkamol/seo-audit?color=f97316" alt="release"></a>
   <img src="https://img.shields.io/badge/node-%E2%89%A518-3c873a" alt="node >= 18">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies">
@@ -630,6 +632,31 @@ survivable in CI instead of being switched off in week two.
 
 ---
 
+## The window, on Linux and Windows
+
+The macOS app is a thin client over a local server, and that server runs anywhere Node does:
+
+```bash
+npx @nurkamol/seo-audit --serve
+```
+
+It opens a browser onto the same window the macOS app draws: a sidebar of kept runs down the left, the report beside it, score ring and all. Everything the command line takes is in the form — the same table that decides what the macOS window reaches decides what this draws, so neither can quietly fall behind the other. Finished runs are kept and listed at `/reports`, two of them can be compared, and on macOS it is **the same folder the app uses**: a crawl started in the window is in the browser's list a second later, because there is one folder rather than two.
+
+Nothing leaves the machine. It binds to the loopback address, which is the whole of its security model.
+
+There is also a **native window for Windows and Linux** built on exactly this: a
+Tauri shell that starts the same server and shows the same report, in
+[`desktop/`](desktop/README.md). It ships a Node inside it, so there is nothing
+to install first. Every release attaches a `setup.exe`, a `.deb` and an
+AppImage, each built on its own runner and then **installed and run there**
+before it is attached. It tells you when there is a new version and offers
+whatever is safe for the way you installed it — `winget upgrade` in place, or
+the command to run, or the release page.
+
+`--no-open` if you would rather it did not open a browser. It opens one when a person ran the command and never when something else did, so the macOS window — which spawns this — is unaffected.
+
+---
+
 ## Hosting it, for people who will not open a terminal
 
 Optional, and off the main path. Everything above is free and runs on your own
@@ -935,6 +962,13 @@ Two rules that keep the tool trustworthy:
 1. **No false positives.** A check that cries wolf gets the whole report ignored. If a pattern is sometimes legitimate, it is a `note`, not an `error`.
 2. **No dependencies.** It must keep running with a bare `npx` on a machine with nothing installed.
 
+```bash
+npm test          # the engine, the Worker and the extension — no install, any platform
+npm run test:all  # and the macOS app's own Swift suite, where there is a toolchain for it
+```
+
+There are two suites and `npm test` runs one. Keeping it portable is the point — it works on a machine with nothing on it. `test:all` runs both and says plainly when it could not run the second, rather than exiting green having skipped half the work.
+
 See [ROADMAP.md](ROADMAP.md) for what is planned, [CHANGELOG.md](CHANGELOG.md) for what changed.
 
 ## Licence

package/bin/seo-audit.mjs

@@ -79,6 +79,9 @@ const HELP = `
     --check-external   also check links pointing off the site. Off by default:
                        other people's servers rate-limit and bot-block, so only
                        a 404, a 410 or no answer at all is ever reported
+    --no-open          with --serve, do not open a browser. It opens one when
+                       a person ran the command and never when something else
+                       did, so this is only for the person who wants neither
     --serve [port]     open the same form the hosted version serves, on this
                        machine (default 4321). No account, no bill, and none of
                        the limits a Worker has — the crawl is only bounded by
@@ -155,6 +158,7 @@ function parseArgs(argv) {
     else if (arg === '--write-sitemap') opts.writeSitemap = value();
     else if (arg === '--write-llms') opts.writeLlms = value();
     else if (arg === '--write-schema') opts.writeSchema = value();
+    else if (arg === '--no-open') opts.noOpen = true;
     else if (arg === '--md') opts.md = value();
     else if (arg === '--html') opts.html = value();
     else if (arg === '--json') opts.json = value();
@@ -335,6 +339,19 @@ if (opts.serve !== undefined) {
     process.stdin.on('end', () => process.exit(0));
     process.stdin.on('close', () => process.exit(0));
   }
+
+  // Opened for a person, never for a parent. The same distinction the pipe
+  // check above already makes: somebody who typed `--serve` wants the page,
+  // and the macOS window — which spawns this and draws its own report — would
+  // get a browser it never asked for on every launch.
+  //
+  // This is the whole of "the desktop UI for Linux and Windows": a command that
+  // opens a window. Failing to open one is not a reason to refuse to serve, so
+  // the URL is printed either way and nothing here throws.
+  if (!stdinIsPipe && !opts.noOpen) {
+    const { openUrl } = await import('../src/open-url.mjs');
+    if (!openUrl(url)) console.log('  Open that address yourself — this system has no launcher I know.\n');
+  }
 } else {
 
 // --- sign in, and stop ----------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurkamol/seo-audit",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Crawl a site's sitemap and check every page for SEO, metadata and structured-data problems that single-page graders miss. Zero dependencies.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "exports": {
     ".": "./src/audit.mjs",
     "./causes": "./src/causes.mjs",
+    "./exports": "./src/exports.mjs",
     "./report": "./src/report.mjs",
     "./score": "./src/score.mjs",
     "./sitemap": "./src/sitemap.mjs",
@@ -29,6 +30,8 @@
   "scripts": {
     "pretest": "node scripts/link-engine.mjs",
     "test": "node --test test/*.test.mjs",
+    "pretest:all": "node scripts/link-engine.mjs",
+    "test:all": "node scripts/test-all.mjs",
     "audit": "node bin/seo-audit.mjs"
   },
   "keywords": [

package/src/exports.mjs

@@ -0,0 +1,84 @@
+// A report, in whatever shape somebody needs it.
+//
+// This owns none of the formats. `html()`, `markdown()` and `csv()` are the
+// writers the command line calls for `--html`, `--md` and `--csv`; the
+// corrected sitemap, the llms.txt and the structured data are whatever the run
+// produced when it was asked. A file downloaded from the window and one written
+// by `seo-audit --csv` are the same file, which is the rule that lets this
+// project have five front ends.
+//
+// What it does own is the **list**: which formats exist, what they are called,
+// and what a saved file is named. That was written out twice — once in the
+// macOS app's `ExportFormat` and once in the Raycast extension — and a third
+// copy for the served window would have been the point at which they started
+// disagreeing about whether "Structured data" is called that.
+//
+// Web-standard only: no `node:fs` here, because the Worker imports it. Writing
+// the file is the caller's job and differs per front end anyway — a browser
+// downloads it, a launcher writes it to Downloads, a window opens a save panel.
+
+import { html, markdown, csv } from './report.mjs';
+
+/** Every shape a report can be written as, in the order somebody wants them. */
+export const FORMATS = [
+  { id: 'html', label: 'HTML report', extension: 'html', mime: 'text/html; charset=utf-8',
+    detail: 'The full report, one file, opens in any browser.' },
+  { id: 'markdown', label: 'Markdown', extension: 'md', mime: 'text/markdown; charset=utf-8',
+    detail: 'For committing, or pasting into a ticket.' },
+  { id: 'csv', label: 'Spreadsheet', extension: 'csv', mime: 'text/csv; charset=utf-8',
+    detail: 'The whole checklist, one row each. For sorting and filtering.' },
+  { id: 'json', label: 'JSON', extension: 'json', mime: 'application/json; charset=utf-8',
+    detail: 'Everything, exactly as the engine produced it.' },
+  { id: 'sitemap', label: 'Corrected sitemap', extension: 'xml', mime: 'application/xml; charset=utf-8',
+    detail: 'The sitemap this site should have had.' },
+  { id: 'llms', label: 'llms.txt', extension: 'txt', mime: 'text/plain; charset=utf-8',
+    detail: "The llms.txt this site should have had, from its own words." },
+  { id: 'schema', label: 'Structured data', extension: 'json', mime: 'application/json; charset=utf-8',
+    detail: 'The JSON-LD this site could add, from what it already says.' },
+];
+
+export const formatById = (id) => FORMATS.find((format) => format.id === id) ?? null;
+
+/** A file name somebody can find again, and that sorts. */
+export function filenameFor(format, host, at = new Date()) {
+  const spec = formatById(format);
+  const stamp = at.toISOString().slice(0, 10);
+  const safe = (host || 'report').replace(/[^a-z0-9.-]+/gi, '-');
+  return `seo-audit-${safe}-${stamp}.${spec?.extension ?? 'txt'}`;
+}
+
+/** The report as text, or the reason there is none.
+ *
+ *  Three of these can legitimately be nothing, and the refusal is the useful
+ *  half: the engine declines to build a sitemap from a crawl that did not see
+ *  the whole site, declines an llms.txt for the same reason, and tells a site
+ *  that already declares all the structured data it could write exactly that.
+ *  Carrying the reason is the difference between "unavailable" and "here is
+ *  why, and here is the run that would work". */
+export function renderExport(format, report) {
+  if (!report?.meta) return { text: null, refused: 'There is no report to write.' };
+
+  const built = (held, text, what) => {
+    if (!held) return { text: null, refused: `This run did not build ${what}.` };
+    return { text, refused: text ? null : held.refused };
+  };
+
+  switch (format) {
+    case 'html':
+      return { text: html(report.findings ?? [], report.meta, { score: report.score }), refused: null };
+    case 'markdown':
+      return { text: markdown(report.findings ?? [], report.meta, { score: report.score }), refused: null };
+    case 'csv':
+      return { text: csv(report.findings ?? [], report.meta, { score: report.score }), refused: null };
+    case 'json':
+      return { text: JSON.stringify(report, null, 2), refused: null };
+    case 'sitemap':
+      return built(report.sitemap, report.sitemap?.xml, 'a sitemap');
+    case 'llms':
+      return built(report.llms, report.llms?.text, 'an llms.txt');
+    case 'schema':
+      return built(report.schema, report.schema?.json, 'any structured data');
+    default:
+      return { text: null, refused: `Unknown format "${format}".` };
+  }
+}

package/src/library.mjs

@@ -0,0 +1,156 @@
+// Runs, kept on disk, for the local server.
+//
+// The macOS window has kept every finished run since 1.23.0 and `--serve` kept
+// none, so somebody on Linux or Windows got one report and lost it the moment
+// they audited something else. A seven-minute crawl should only ever happen
+// once, and that is not a macOS-only claim.
+//
+// It writes **the same folder the app uses**, in the same shape, so a run
+// started in the window is in the browser's list a second later and the other
+// way round — nothing is synchronised, exported or copied, because there is one
+// folder and both front ends read it.
+//
+// This is Node, and `worker/index.mjs` must not be: it runs on Cloudflare too,
+// where there is no filesystem. So the server hands the worker an object with
+// these four methods and the worker calls them if they are there. A deployed
+// Worker passes nothing and has no library, which is correct — a shared host
+// keeping strangers' crawls is a thing nobody asked for.
+
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync, rmSync, statSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/** Where an application keeps documents it manages, per platform.
+ *
+ *  macOS is `Application Support`, and deliberately the *same* path
+ *  `Support.directory()` uses on the Swift side — named for the bundle id
+ *  rather than the display name — so the window and the browser share one
+ *  library rather than each having their own.
+ *
+ *  Caches would be wrong everywhere: the system may delete those, and seven
+ *  minutes of crawling is not a cache. */
+export function libraryRoot(env = process.env, os = platform()) {
+  if (env.SEO_AUDIT_HOME) return env.SEO_AUDIT_HOME;
+  const home = homedir();
+  if (os === 'darwin') return join(home, 'Library', 'Application Support', 'seo-audit');
+  if (os === 'win32') {
+    return join(env.APPDATA || join(home, 'AppData', 'Roaming'), 'seo-audit');
+  }
+  // Linux and the BSDs: the XDG basedir spec, which says $XDG_DATA_HOME and
+  // falls back to ~/.local/share.
+  return join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'seo-audit');
+}
+
+/** How many runs to keep. The same bound the window applies, for the same
+ *  reason: this is a list to click rather than an archive. */
+const KEEP = 40;
+
+/** A store the Worker can call without knowing it is talking to a filesystem. */
+export function library(root = libraryRoot()) {
+  const folder = join(root, 'reports');
+  const indexFile = join(root, 'index.json');
+  mkdirSync(folder, { recursive: true });
+
+  const readIndex = () => {
+    if (!existsSync(indexFile)) return [];
+    try {
+      const rows = JSON.parse(readFileSync(indexFile, 'utf8'));
+      // An index entry whose file is gone is a row that opens onto nothing,
+      // which is worse than not listing it — a folder can be emptied by a sync
+      // tool without the index being told.
+      return Array.isArray(rows)
+        ? rows.filter((row) => row?.id && existsSync(join(folder, `${row.id}.json`)))
+        : [];
+    } catch {
+      return [];
+    }
+  };
+
+  const writeIndex = (rows) => {
+    try {
+      writeFileSync(indexFile, JSON.stringify(rows, null, 2));
+    } catch {
+      /* a library that cannot be written is not a reason to lose the report */
+    }
+  };
+
+  return {
+    /** Every kept run, newest first. */
+    list() {
+      return readIndex().sort((a, b) => String(b.finishedAt).localeCompare(String(a.finishedAt)));
+    },
+
+    /** One run, exactly as the engine wrote it. `null` when it is not there. */
+    read(id) {
+      // The id comes off a URL, so it is checked rather than trusted: anything
+      // but a UUID cannot become a path.
+      if (!/^[0-9a-f-]{36}$/i.test(id ?? '')) return null;
+      try {
+        return JSON.parse(readFileSync(join(folder, `${id}.json`), 'utf8'));
+      } catch {
+        return null;
+      }
+    },
+
+    /** Keep a finished run. `payload` is what the engine produced, byte for
+     *  byte — not this server's idea of it, so a report saved by one version
+     *  still opens in the next and `jq` works on it. */
+    keep(payload, { site, finishedAt = new Date().toISOString() } = {}) {
+      const id = randomUUID();
+      const counts = { error: 0, warn: 0, info: 0 };
+      for (const finding of payload.findings ?? []) counts[finding.level] += 1;
+
+      let host = site;
+      try {
+        host = new URL(payload.meta?.origin ?? site).host;
+      } catch {
+        /* keep whatever was passed */
+      }
+
+      const row = {
+        id,
+        host,
+        site: payload.meta?.origin ?? site,
+        finishedAt,
+        pages: payload.meta?.pages ?? 0,
+        findings: (payload.findings ?? []).length,
+        causes: (payload.causes ?? []).length,
+        errors: counts.error,
+        warnings: counts.warn,
+        // The same field the window writes, so one list shows both.
+        ...(typeof payload.score?.score === 'number' ? { score: payload.score.score } : {}),
+      };
+
+      try {
+        writeFileSync(join(folder, `${id}.json`), JSON.stringify(payload));
+      } catch {
+        return null;
+      }
+
+      const rows = [row, ...readIndex()];
+      for (const old of rows.slice(KEEP)) {
+        try {
+          rmSync(join(folder, `${old.id}.json`), { force: true });
+        } catch {
+          /* already gone */
+        }
+      }
+      writeIndex(rows.slice(0, KEEP));
+      return row;
+    },
+
+    /** Where the files are, and what they take up — "small" is a claim
+     *  somebody is entitled to check. */
+    where: () => folder,
+    bytes() {
+      return readIndex().reduce((total, row) => {
+        try {
+          return total + statSync(join(folder, `${row.id}.json`)).size;
+        } catch {
+          return total;
+        }
+      }, 0);
+    },
+  };
+}

package/src/open-url.mjs

@@ -0,0 +1,49 @@
+// Opening a URL in whatever the person's system calls a browser.
+//
+// Three commands for three platforms and no dependency, which is the whole
+// reason this is nine lines rather than an `open` package. Detached and with
+// its output thrown away: the launcher exits immediately on every platform, and
+// a server that waits on it would hang on the one that does not.
+
+import { spawn } from 'node:child_process';
+
+/** The command that opens a URL, per platform. `null` where there is nothing
+ *  to try — a container, or a system this has no answer for. */
+export function opener(platform = process.platform) {
+  switch (platform) {
+    case 'darwin':
+      return { command: 'open', args: [] };
+    // `start` is a shell builtin rather than a program, so it needs cmd. The
+    // empty string is the window title `start` otherwise steals from the URL,
+    // and leaving it out is the classic bug where nothing opens.
+    case 'win32':
+      return { command: 'cmd', args: ['/c', 'start', ''] };
+    case 'linux':
+    case 'freebsd':
+    case 'openbsd':
+      return { command: 'xdg-open', args: [] };
+    default:
+      return null;
+  }
+}
+
+/** Open a URL. Returns false when there was nothing to try, or when the
+ *  launcher could not be started — never throws, because failing to open a
+ *  browser is not a reason for a server not to run. The URL is already on
+ *  screen either way. */
+export function openUrl(url, { platform = process.platform, spawnFn = spawn } = {}) {
+  const how = opener(platform);
+  if (!how) return false;
+  try {
+    const child = spawnFn(how.command, [...how.args, url], {
+      stdio: 'ignore',
+      detached: true,
+    });
+    // Not waited on: the parent is a server that should outlive the launcher.
+    child.on?.('error', () => {});
+    child.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/options.mjs

@@ -23,21 +23,48 @@
  */
 export const OPTIONS = [
   // --- what a run does ----------------------------------------------------
-  { flag: '--limit', query: 'limit', app: true },
-  { flag: '--concurrency', query: 'concurrency', app: true },
-  { flag: '--check-external', query: 'external', app: true },
-  { flag: '--sitemap', query: 'sitemap', app: true },
-  { flag: '--browser', query: 'browser', app: true },
-  { flag: '--os', query: 'os', app: true },
-  { flag: '--user-agent', query: 'userAgent', app: true },
-  { flag: '--search-console', query: 'search-console', app: true },
+  { flag: '--limit', query: 'limit', app: true,
+    field: { type: 'number', label: 'Pages at most', min: 1,
+             help: 'A big site is minutes. Preview first if you are not sure this is the right one.' } },
+  { flag: '--concurrency', query: 'concurrency', app: true,
+    field: { type: 'select', label: 'Speed',
+             // The same three the macOS window offers, so "Gentle" means the
+             // same thing in both. The numbers live in one place.
+             choices: [['', 'Normal — 6 at a time'], ['1', 'Gentle — one at a time, for a server that rate limits'],
+                       ['12', 'Fast — 12 at a time, if you own the server']] } },
+  { flag: '--check-external', query: 'external', app: true,
+    field: { type: 'checkbox', label: 'Check outbound links too', value: '1',
+             help: 'Slower, and other people\'s servers decide how much slower.' } },
+  { flag: '--sitemap', query: 'sitemap', app: true,
+    field: { type: 'url', label: 'Sitemap', placeholder: 'Found automatically',
+             help: 'Only if robots.txt does not declare one and it is somewhere unusual.' } },
+  { flag: '--browser', query: 'browser', app: true,
+    field: { type: 'agent', label: 'Ask as', which: 'browser' } },
+  { flag: '--os', query: 'os', app: true,
+    field: { type: 'agent', label: 'On', which: 'os' } },
+  { flag: '--user-agent', query: 'userAgent', app: true,
+    field: { type: 'text', label: 'Or a user agent of your own', placeholder: 'Replaces the two menus above' } },
+  { flag: '--search-console', query: 'search-console', app: true,
+    // Reads somebody's Search Console, so it is only offered where the
+    // deployment has said those credentials are the visitor's own.
+    field: { type: 'text', label: 'Search Console property', placeholder: 'sc-domain:example.com',
+             needs: 'ALLOW_SEARCH_CONSOLE',
+             help: 'A domain property is named sc-domain:example.com, not by its URL.' } },
   { flag: '--write-sitemap', query: 'sitemap-out', app: true, via: 'the Export menu' },
   { flag: '--write-llms', query: 'llms-out', app: true, via: 'the Export menu' },
   { flag: '--write-schema', query: 'schema-out', app: true, via: 'the Export menu' },
-  { flag: '--ignore', query: 'ignore', app: true, via: 'right-clicking a finding, and the Settings list' },
-  { flag: '--psi', query: 'psi', app: true, via: 'Settings → Performance' },
-  { flag: '--psi-sample', query: 'psi-sample', app: true, via: 'Settings → Performance' },
-  { flag: '--psi-strategy', query: 'psi-strategy', app: true, via: 'Settings → Performance' },
+  { flag: '--ignore', query: 'ignore', app: true, via: 'right-clicking a finding, and the Settings list',
+    field: { type: 'text', label: 'Silence these checks', placeholder: 'og-webp, img-srcset',
+             help: 'Check ids, comma separated. They are still counted, and the report says how many.' } },
+  { flag: '--psi', query: 'psi', app: true, via: 'Settings → Performance',
+    field: { type: 'text', label: 'Measure performance', placeholder: '/ or /blog/**',
+             needs: 'ALLOW_PSI',
+             help: 'Asks Google. A URL, a path, or a glob — and it spends the quota of whoever runs this.' } },
+  { flag: '--psi-sample', query: 'psi-sample', app: true, via: 'Settings → Performance',
+    field: { type: 'number', label: 'Pages to measure', min: 1, needs: 'ALLOW_PSI' } },
+  { flag: '--psi-strategy', query: 'psi-strategy', app: true, via: 'Settings → Performance',
+    field: { type: 'select', label: 'Measured as', needs: 'ALLOW_PSI',
+             choices: [['', 'A phone — what Google indexes with'], ['desktop', 'A desktop']] } },
   { flag: '--since', query: null, app: 'not yet — it needs a date picker and a sense of when the last run was, which the window has in the library and does not offer yet' },
   { flag: '--exclude', query: null, app: 'not yet — a list of patterns needs somewhere to live in Settings, and one text field would be worse than nothing' },
 
@@ -49,6 +76,8 @@ export const OPTIONS = [
   { flag: '--md', query: null, app: true, via: 'the Export menu' },
   { flag: '--html', query: null, app: true, via: 'the Export menu' },
 
+  { flag: '--no-open', query: null, app: 'the window is the browser this would open — it spawns --serve itself and draws the report natively, and the pipe it hands over is what already stops a browser appearing' },
+
   // --- deliberately not in a window ---------------------------------------
   { flag: '--help', query: null, app: 'a window has no command line to explain' },
   { flag: '--version', query: null, app: 'the sidebar shows it, and offers every other one' },
@@ -74,6 +103,21 @@ export const OPTIONS = [
 export const runParameters = () =>
   OPTIONS.filter((o) => o.app === true && o.query).map(({ flag, query }) => ({ flag, query }));
 
+/** The controls a form should draw, in the order they are declared above.
+ *
+ *  Its own list rather than a second table: the hosted form used to hard-code
+ *  two inputs while the engine took a dozen parameters, so somebody at a
+ *  browser could reach a sixth of what somebody at a terminal could. Adding a
+ *  flag with a `field` now adds the control, and a flag without one is simply
+ *  not offered — which is a decision, written down beside the flag it is about.
+ *
+ *  `allow` answers the gates: PageSpeed spends somebody's quota and Search
+ *  Console reads somebody's account, so neither is drawn unless the deployment
+ *  has said those are the visitor's own to spend. */
+export const formFields = (allow = () => true) =>
+  OPTIONS.filter((o) => o.field && o.query && (!o.field.needs || allow(o.field.needs)))
+    .map(({ flag, query, field }) => ({ flag, query, ...field }));
+
 /** Everything the window does not reach, and why. Served so the answer is
  *  discoverable rather than only being in a source file. */
 export const notInApp = () =>

package/src/report.mjs

@@ -104,7 +104,9 @@ export function terminal(findings, meta, { score } = {}) {
     lines.push(`  ${paint(bold(`${score.score}`))}${dim('/100')}   ${paint(bold(score.grade))}   ${paint(scoreBar(score.score))}`);
     lines.push(
       dim(
-        `  ${score.lost} points across ${score.checks.failed} check${score.checks.failed === 1 ? '' : 's'} · ` +
+        `  ${score.checks.failed
+          ? `${score.lost} points across ${score.checks.failed} check${score.checks.failed === 1 ? '' : 's'}`
+          : 'Nothing took points off'} · ` +
           `${score.checks.passed} passed · ${score.checks.skipped} did not apply`,
       ),
     );
@@ -344,7 +346,9 @@ function scoreMarkdown(score) {
   );
   out.push('');
   out.push(
-    `${score.lost} points across ${score.checks.failed} check${score.checks.failed === 1 ? '' : 's'}. ` +
+    `${score.checks.failed
+      ? `${score.lost} points across ${score.checks.failed} check${score.checks.failed === 1 ? '' : 's'}. `
+      : 'Nothing took points off. '}` +
       `${score.checks.passed} passed and ${score.checks.skipped} did not apply.` +
       (score.ifErrorsFixed > score.score ? ` Clear the errors alone and it is **${score.ifErrorsFixed}**.` : ''),
   );
@@ -730,7 +734,7 @@ export function csv(findings, meta, { score } = {}) {
   return `\uFEFF${[columns, ...rows].map((row) => row.map(cell).join(',')).join('\r\n')}\r\n`;
 }
 
-export function html(findings, meta, { backHref, backLabel = 'New audit', score } = {}) {
+export function reportParts(findings, meta, { backHref, backLabel = 'New audit', score } = {}) {
   const n = counts(findings);
   const esc = (s) =>
     String(s ?? '')
@@ -767,8 +771,13 @@ export function html(findings, meta, { backHref, backLabel = 'New audit', score
     </div>
     <div class="story">
       <h2>${score.score} out of 100</h2>
-      <p class="lede">${score.lost} points across ${plural(score.checks.failed, 'check')}.
-        ${score.checks.passed} passed, ${score.checks.skipped} did not apply.${
+      <p class="lede">${
+        // "0 points across 0 checks" is what a perfect score used to read as,
+        // which is arithmetic rather than a sentence.
+        score.checks.failed
+          ? `${score.lost} points across ${plural(score.checks.failed, 'check')}. `
+          : 'Nothing took points off. '
+      }${score.checks.passed} passed, ${score.checks.skipped} did not apply.${
           score.ifErrorsFixed > score.score
             ? ` Clear the errors alone and it is <b>${score.ifErrorsFixed}</b>.`
             : ''
@@ -858,13 +867,15 @@ export function html(findings, meta, { backHref, backLabel = 'New audit', score
       .join('')}`;
   };
 
-  return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>SEO audit — ${esc(meta.origin)}</title>
-<style>
+  // The stylesheet and the report, separately.
+  //
+  // `html()` composes them into a document, which is what `--html` writes
+  // and what has to keep working with no network and no assets. The local
+  // server composes the same two into its own shell instead, so the report
+  // in a browser and the report in a file are the same report rather than
+  // two renderings that drift — which is the rule this project applies to
+  // every other pair of front ends.
+  const css = `
   :root {
     color-scheme: light dark;
     --bg: #fff;
@@ -1161,10 +1172,9 @@ export function html(findings, meta, { backHref, backLabel = 'New audit', score
     .finding a[href^="http"]::after { content: " (" attr(href) ")"; font-size: .8em; color: #4b5563; word-break: break-all; }
     .back, .js-only { display: none !important; }
   }
-</style>
-</head>
-<body>
-<main>
+`;
+
+  const body = `
   <div class="bar">
     <a class="mark" href="https://github.com/nurkamol/seo-audit">seo<span>-</span>audit</a>
     ${backHref ? `<a class="back" href="${esc(backHref)}">← ${esc(backLabel)}</a>` : ''}
@@ -1234,7 +1244,24 @@ export function html(findings, meta, { backHref, backLabel = 'New audit', score
     <a href="https://pagespeed.web.dev">PageSpeed Insights</a> when <code>--psi</code> is used, never estimated here.
     Generated by <a href="https://github.com/nurkamol/seo-audit">seo-audit</a>.
   </footer>
-</main>
+`;
+
+  return { css, body, title: `SEO audit — ${esc(meta.origin)}` };
+}
+
+/** Self-contained HTML: one file, no assets, safe to email or attach. */
+export function html(findings, meta, options = {}) {
+  const { css, body, title } = reportParts(findings, meta, options);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>${css}</style>
+</head>
+<body>
+<main>${body}</main>
 </body>
 </html>
 `;

package/src/serve.mjs

@@ -13,6 +13,7 @@ import { Readable } from 'node:stream';
 import { randomUUID } from 'node:crypto';
 
 import { handle } from '../worker/index.mjs';
+import { library } from './library.mjs';
 
 /** Start the local UI. Returns `{ url, close }`.
  *
@@ -50,6 +51,16 @@ export async function serve({ port = 4321, host = '127.0.0.1', maxPages, allowed
     CAN_READ_CERTIFICATES: '1',
   };
 
+  // Every finished run, kept — and kept in the folder the macOS window already
+  // uses, so a crawl started in one is in the other's list a second later.
+  //
+  // Handed over as an object rather than imported by the Worker, which must
+  // stay web-standard: this is `node:fs`, and Cloudflare has no filesystem. A
+  // deployed Worker is passed nothing and simply has no library, which is the
+  // right answer for a shared host — keeping strangers' crawls is a thing
+  // nobody asked for.
+  env.STORE = library();
+
   const server = createServer(async (incoming, outgoing) => {
     try {
       const url = `http://${incoming.headers.host ?? `${host}:${port}`}${incoming.url}`;