@reddoorla/maintenance 0.10.4 → 0.10.6

package/README.md

@@ -2,7 +2,14 @@
 
 Canonical maintenance configs, audits, and recipes for the reddoor SvelteKit + Prismic fleet.
 
-A single CLI (`reddoor-maint`) that runs **audits** to inspect a site, **recipes** to mutate one (branch-isolated, idempotent, never on a dirty tree), and ships the **canonical configs** every reddoor site shares (eslint, prettier, lighthouse, playwright-a11y, svelte). Designed to run against either a single local site or a fleet declared in an inventory file.
+A single CLI (`reddoor-maint`) covering the full operator workflow:
+
+- **Audits** inspect a site (lighthouse, a11y, security, lint, deps).
+- **Recipes** mutate one (branch-isolated, idempotent, never on a dirty tree) — start with [`init`](#init) for fresh sites.
+- **Reports** ([per-site monthly/quarterly emails](#reports-per-site-maintenancetesting-emails)) draft + send client-facing maintenance + testing summaries, backed by Airtable as the source of truth and Resend for delivery.
+- **Canonical configs** (eslint, prettier, lighthouserc, playwright-a11y, svelte) ship as importable presets every reddoor site shares.
+
+Designed to run against either a single local site or a fleet declared in an inventory file.
 
 ```bash
 pnpm add -D @reddoorla/maintenance
@@ -46,6 +53,7 @@ reddoor-maint list-recipes      # recipe descriptions
 
 reddoor-maint init [site]       # full onboarding chain (preferred entrypoint)
 reddoor-maint audit [site]      # run audits
+reddoor-maint report [site]     # draft / send per-site maintenance + testing emails (see Reports)
 reddoor-maint sync-configs [site]
 reddoor-maint bump-deps [site]
 reddoor-maint convert-to-pnpm [site]
@@ -76,7 +84,7 @@ reddoor-maint upgrade svelte-4-to-5 [site]
 
 ## Recipes
 
-Each recipe is `(site, opts?) => Promise<RecipeResult>` and is exported from the package entry as a library function too:
+Each recipe is `(site, opts?) => Promise<RecipeResult>` and is also exported from the package entry as a library function:
 
 ```ts
 import {
@@ -99,13 +107,11 @@ Shared contract — every recipe:
 - **Is idempotent** — re-running on the already-applied state returns `{ status: "noop", commits: [] }` without creating a branch.
 - **Returns a `RecipeResult`** — `{ recipe, site, status: "applied" | "noop" | "failed", commits: string[], notes?: string }`.
 
-### `sync-configs`
-
-Writes the canonical config templates into the site (eslint, prettier, lighthouserc, playwright config, svelte config) and merges the canonical entries into `.gitignore`. Each config is its own commit. `--dry` reports the planned diff (including gitignore drift) without writing. `--only <name>[,<name>]` restricts to a subset.
+### `init`
 
-### `bump-deps`
+One-shot guided onboarding — the recommended entrypoint for a fresh site. Runs `convert-to-pnpm → onboard → sync-configs → svelte-codemods → a11y-fixtures-page → audit` in sequence. Each underlying recipe still creates its own branch — `init` is a thin orchestrator, not a branch-collapser. Stops the chain on the first `failed` recipe or uncaught error; `noop` results continue the chain. Exit code is 1 if any step failed _or_ the final audit pass reports a `fail`.
 
-Pre-flights that the site is on pnpm (refuses with a clear remediation if `package-lock.json` or `yarn.lock` is present without `pnpm-lock.yaml`), runs `pnpm install` to ensure the lockfile is current, then `pnpm outdated --json` to decide whether anything needs upgrading. If yes: creates a branch and runs `pnpm up` scoped to the requested `--group` (patch / minor / major), then commits the result. `noop` if nothing's out of date.
+The remaining sections describe each step `init` invokes (in chain order), plus the standalone recipes that aren't part of onboarding.
 
 ### `convert-to-pnpm`
 
@@ -115,21 +121,25 @@ Removes the npm or yarn lockfile, pins `packageManager: pnpm@X.Y.Z` in `package.
 
 Adds `@reddoorla/maintenance` + the audit deps (`@lhci/cli`, `@playwright/test`, `@axe-core/playwright`) to the site's `devDependencies` if they're missing. Audit dep versions come from `src/configs/baseline-versions.ts` so they can't drift from the rest of the package. The maintenance dep is pinned to a caret range against this package's own version at runtime — no manual syncing required at each minor bump. Refuses with `{ status: "failed", notes: "run convert-to-pnpm first" }` if the site has no `pnpm-lock.yaml`.
 
-### `svelte-codemods`
+### `sync-configs`
 
-Standalone codemod pass for sites already on Svelte 5. Applies the same gotcha codemods the full `svelte-4-to-5` recipe runs (`export let` → `$props()`, `on:event` → `onevent`, `$:` → `$derived`/`$effect`, `$$props.class` rewrite, `$$restProps` → destructured `...rest`, `$state` + `$effect` → `$derived`). Useful when post-upgrade Svelte 5 surfaces new strictness warnings and the fleet needs a clean re-application.
+Writes the canonical config templates into the site (eslint, prettier, lighthouserc, playwright config, svelte config) and merges the canonical entries into `.gitignore`. Each config is its own commit. `--dry` reports the planned diff (including gitignore drift) without writing. `--only <name>[,<name>]` restricts to a subset.
 
-### `upgrade svelte-4-to-5`
+### `svelte-codemods`
 
-The full 7-step Svelte 4 → 5 migration: bump framework versions, migrate `svelte.config.js`, run the official `svelte-migrate` codemod, run `@tailwindcss/upgrade`, apply gotcha codemods over `src/**/*.svelte`, verify with `pnpm install` + `pnpm run check`, and write a `MIGRATION_SVELTE_5.md` summary. Each step is its own commit; the file leaves a record of what ran and what may need manual review.
+Standalone codemod pass for sites already on Svelte 5. Applies the same gotcha codemods the full `svelte-4-to-5` recipe runs (`export let` → `$props()`, `on:event` → `onevent`, `$:` → `$derived`/`$effect`, `$$props.class` rewrite, `$$restProps` → destructured `...rest`, `$state` + `$effect` → `$derived`). Useful when post-upgrade Svelte 5 surfaces new strictness warnings and the fleet needs a clean re-application.
 
 ### `a11y-fixtures-page`
 
 Writes a starter `src/routes/dev/a11y-fixtures/+page.svelte` if the route doesn't already exist. The `lighthouse` and `playwright-a11y` configs both target this URL — newly-onboarded sites need the route to exist for either audit to pass. The template is intentionally generic (semantic landmarks + headings + a relative link); operator edits to an existing page are never clobbered.
 
-### `init`
+### `bump-deps` _(standalone — not part of `init`)_
+
+Pre-flights that the site is on pnpm (refuses with a clear remediation if `package-lock.json` or `yarn.lock` is present without `pnpm-lock.yaml`), runs `pnpm install` to ensure the lockfile is current, then `pnpm outdated --json` to decide whether anything needs upgrading. If yes: creates a branch and runs `pnpm up` scoped to the requested `--group` (patch / minor / major), then commits the result. `noop` if nothing's out of date.
 
-One-shot guided onboarding: runs `convert-to-pnpm → onboard → sync-configs → svelte-codemods → a11y-fixtures-page → audit` in sequence against a site. Each underlying recipe still creates its own branch — `init` is a thin orchestrator, not a branch-collapser. Stops the chain on the first `failed` recipe or uncaught error; `noop` results continue the chain. Exit code is 1 if any step failed _or_ the final audit pass reports a `fail`.
+### `upgrade svelte-4-to-5` _(standalone — not part of `init`)_
+
+The full 7-step Svelte 4 → 5 migration: bump framework versions, migrate `svelte.config.js`, run the official `svelte-migrate` codemod, run `@tailwindcss/upgrade`, apply gotcha codemods over `src/**/*.svelte`, verify with `pnpm install` + `pnpm run check`, and write a `MIGRATION_SVELTE_5.md` summary. Each step is its own commit; the file leaves a record of what ran and what may need manual review.
 
 ---
 
@@ -190,22 +200,30 @@ Pass `--fleet <path>` to run a command against multiple sites declared in an inv
 
 ## Library usage
 
-The package's main entry exports every recipe and audit so you can wire them into custom tooling (CI jobs, scheduled scripts, alternative CLIs):
+The package's main entry exports every recipe, audit, and report function so you can wire them into custom tooling (CI jobs, scheduled scripts, alternative CLIs):
 
 ```ts
 import {
   // recipes
-  syncConfigs,
-  bumpDeps,
+  init,
   convertToPnpm,
   onboard,
+  syncConfigs,
   svelteCodemods,
+  a11yFixturesPage,
+  bumpDeps,
   upgradeSvelte4to5,
 
   // audits
   runAudits,
   ALL_AUDIT_NAMES,
 
+  // reports (per-site maintenance / testing emails)
+  draftReportForSite,
+  sendApprovedReports,
+  renderReportHtml,
+  findDueReports,
+
   // recipe registry
   ALL_RECIPE_NAMES,
   isRecipeName,

package/dist/cli/bin.js

@@ -1104,7 +1104,7 @@ async function securityAudit(ctx) {
 }
 
 // src/audits/lighthouse.ts
-import { readFile as readFile4, writeFile, mkdtemp, rm } from "fs/promises";
+import { readFile as readFile4, writeFile, mkdtemp, rm, readdir } from "fs/promises";
 import { tmpdir } from "os";
 import { join as join4 } from "path";
 
@@ -1166,6 +1166,32 @@ async function readSiteConfig(sitePath) {
   return out;
 }
 
+// src/util/free-port.ts
+import { createServer } from "net";
+async function findFreePort() {
+  return new Promise((resolve10, reject) => {
+    const server = createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (typeof addr === "object" && addr) {
+        const port = addr.port;
+        server.close(() => resolve10(port));
+      } else {
+        server.close();
+        reject(new Error("findFreePort: could not determine assigned port from socket"));
+      }
+    });
+  });
+}
+function withFreePort(url, port) {
+  const u = new URL(url);
+  u.hostname = "localhost";
+  u.port = String(port);
+  return u.toString();
+}
+
 // src/audits/lighthouse.ts
 async function readJsonMaybe(path) {
   try {
@@ -1175,6 +1201,21 @@ async function readJsonMaybe(path) {
     return null;
   }
 }
+async function readLhrEntries(resultsDir) {
+  const files = await readdir(resultsDir).catch(() => []);
+  const entries = [];
+  for (const f of files) {
+    if (!f.startsWith("lhr-") || !f.endsWith(".json")) continue;
+    const lhr = await readJsonMaybe(join4(resultsDir, f));
+    if (!lhr || !lhr.categories) continue;
+    const summary = {};
+    for (const [k, v] of Object.entries(lhr.categories)) {
+      if (typeof v?.score === "number") summary[k] = v.score;
+    }
+    entries.push({ url: lhr.requestedUrl, summary });
+  }
+  return entries;
+}
 function averageSummaries(entries) {
   if (entries.length === 0) return {};
   const sums = {};
@@ -1206,13 +1247,19 @@ async function lighthouseAudit(ctx) {
   const site = ctx.site;
   const label = siteLabel(site);
   const siteCfg = await readSiteConfig(site.path);
-  const resolvedConfig = siteCfg.lighthouseUrl ? {
+  const port = await findFreePort();
+  const baseUrl = siteCfg.lighthouseUrl ?? lighthouseConfig.ci.collect.url[0];
+  const resolvedConfig = {
     ...lighthouseConfig,
     ci: {
       ...lighthouseConfig.ci,
-      collect: { ...lighthouseConfig.ci.collect, url: [siteCfg.lighthouseUrl] }
+      collect: {
+        ...lighthouseConfig.ci.collect,
+        url: [withFreePort(baseUrl, port)],
+        startServerCommand: `npm run vite:dev -- --port ${port} --strictPort`
+      }
     }
-  } : lighthouseConfig;
+  };
   const configDir = await mkdtemp(join4(tmpdir(), "reddoor-lhci-"));
   const configPath = join4(configDir, "lighthouserc.json");
   await writeFile(configPath, JSON.stringify(resolvedConfig), "utf-8");
@@ -1242,13 +1289,13 @@ async function lighthouseAudit(ctx) {
     throw err;
   }
   await rm(configDir, { recursive: true, force: true });
-  const manifest = await readJsonMaybe(join4(resultsDir, "manifest.json"));
-  if (!manifest || manifest.length === 0) {
+  const manifest = await readLhrEntries(resultsDir);
+  if (manifest.length === 0) {
     return {
       audit: "lighthouse",
       site: label,
       status: "fail",
-      summary: `lighthouse: no manifest written (exit ${raw.code})${raw.stderr ? ` \u2014 ${raw.stderr.slice(0, 200)}` : ""}`
+      summary: `lighthouse: no lhr-*.json written (exit ${raw.code})${raw.stderr ? ` \u2014 ${raw.stderr.slice(0, 200)}` : ""}`
     };
   }
   const assertionResults = await readJsonMaybe(join4(resultsDir, "assertion-results.json")) ?? [];
@@ -1323,6 +1370,37 @@ async function readJsonMaybe2(path) {
     return null;
   }
 }
+function buildPlaywrightConfig(port, sitePath) {
+  return `import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: ".",
+  testMatch: /.*\\.spec\\.ts$/,
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? "github" : "list",
+  use: {
+    baseURL: "http://localhost:${port}",
+    trace: "on-first-retry",
+  },
+  webServer: {
+    // --strictPort: refuse to bump to a different port if ours is taken,
+    //   so the audit fails loudly instead of probing a zombie.
+    // reuseExistingServer:false: never reuse \u2014 we control the lifecycle.
+    // cwd: playwright's default webServer.cwd is the config file's
+    //   directory. Our config lives in /tmp so without this override,
+    //   "npm run vite:dev" tries to read /tmp/.../package.json and
+    //   ENOENTs before vite ever starts. Caltex 2026-05-28 (0.10.5).
+    command: "npm run vite:dev -- --port ${port} --strictPort",
+    url: "http://localhost:${port}/dev/a11y-fixtures",
+    cwd: ${JSON.stringify(sitePath)},
+    reuseExistingServer: false,
+    timeout: 120_000,
+  },
+});
+`;
+}
 function buildSpec() {
   return `import { test, expect } from "@playwright/test";
 import AxeBuilder from "@axe-core/playwright";
@@ -1376,19 +1454,26 @@ async function a11yAudit(ctx) {
   const specDir = await mkdtemp2(join5(tmpdir2(), "reddoor-a11y-spec-"));
   const specPath = join5(specDir, "a11y.spec.ts");
   await writeFile2(specPath, buildSpec(), "utf-8");
+  const port = await findFreePort();
+  const configPath = join5(specDir, "playwright.config.ts");
+  await writeFile2(configPath, buildPlaywrightConfig(port, site.path), "utf-8");
   const resultsPath = join5(site.path, RESULTS_REL);
   await rm2(join5(site.path, ".reddoor-a11y"), { recursive: true, force: true });
   let raw;
   try {
-    raw = await spawn2("npx", ["--yes", "playwright", "test", "--reporter=line", specPath], {
-      cwd: site.path,
-      env: { ...process.env, REDDOOR_A11Y_OUTPUT: resultsPath },
-      // playwright on a cold tree downloads Chrome, boots the site's dev
-      // server, and runs axe over every configured route. The shared 30 s
-      // default in runAudits is fine for deps/lint/security but starves
-      // playwright (mirrors the lighthouse fix shipped earlier).
-      timeoutMs: 5 * 6e4
-    });
+    raw = await spawn2(
+      "npx",
+      ["--yes", "playwright", "test", `--config=${configPath}`, "--reporter=line", specPath],
+      {
+        cwd: site.path,
+        env: { ...process.env, REDDOOR_A11Y_OUTPUT: resultsPath },
+        // playwright on a cold tree downloads Chrome, boots the site's dev
+        // server, and runs axe over every configured route. The shared 30 s
+        // default in runAudits is fine for deps/lint/security but starves
+        // playwright (mirrors the lighthouse fix shipped earlier).
+        timeoutMs: 5 * 6e4
+      }
+    );
   } catch (err) {
     await rm2(specDir, { recursive: true, force: true });
     const e = err;
@@ -1550,7 +1635,7 @@ async function resolveSites(input) {
 }
 
 // src/cli/fleet/clone-if-needed.ts
-import { stat, readdir, mkdir } from "fs/promises";
+import { stat, readdir as readdir2, mkdir } from "fs/promises";
 import { isAbsolute as isAbsolute2, join as join6 } from "path";
 function deriveNameFromRepoUrl(repoUrl) {
   const slash = repoUrl.split("/").pop() ?? repoUrl;
@@ -1578,7 +1663,7 @@ async function isNonEmptyDir(path) {
   try {
     const s = await stat(path);
     if (!s.isDirectory()) return false;
-    const entries = await readdir(path);
+    const entries = await readdir2(path);
     return entries.length > 0;
   } catch {
     return false;