@reddoorla/maintenance 0.9.0 → 0.10.1

package/README.md

@@ -15,19 +15,26 @@ pnpm reddoor-maint --help
 
 A reddoor site goes through this sequence the first time you adopt the package. Each recipe is idempotent — running it again on an already-onboarded site is a `noop`.
 
+```bash
+pnpm reddoor-maint init
+```
+
+`init` runs the whole chain in order against the current directory (or `init [site]` for an explicit path). It's a thin orchestrator — every underlying recipe still creates its own branch and stops on a dirty tree, so the operator ends up with a stack of `maint/<recipe>-<ts>` branches to PR.
+
 ```text
-convert-to-pnpm  →  onboard  →  sync-configs  →  svelte-codemods  →  audit
+convert-to-pnpm  →  onboard  →  sync-configs  →  svelte-codemods  →  a11y-fixtures-page  →  audit
 ```
 
-| Step | Recipe            | What it does                                                                                                                                                                                                                  |
-| ---- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1    | `convert-to-pnpm` | Removes `package-lock.json` / `yarn.lock`, pins `packageManager: pnpm@…`, rewrites `npm` references in scripts, runs `pnpm install` to materialise `pnpm-lock.yaml`.                                                          |
-| 2    | `onboard`         | Installs `@reddoorla/maintenance` + the audit deps (`@lhci/cli`, `@playwright/test`, `@axe-core/playwright`) on the site. Pins the maintenance dep to a caret range against this package's own version at runtime.            |
-| 3    | `sync-configs`    | Writes the canonical config templates into the site (eslint, prettier, lighthouserc, playwright config, svelte config) and merges canonical entries into `.gitignore`.                                                        |
-| 4    | `svelte-codemods` | Optional cleanup pass applying the Svelte 5 gotcha codemods (`export let` → `$props()`, `on:event` → `onevent`, `$:` → `$derived`/`$effect`, etc.) for sites that surface new strictness warnings after the original upgrade. |
-| 5    | `audit`           | Runs `deps`, `lighthouse`, `a11y`, `security`, `lint` — see [Audits](#audits).                                                                                                                                                |
+| Step | Recipe               | What it does                                                                                                                                                                                                                  |
+| ---- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | `convert-to-pnpm`    | Removes `package-lock.json` / `yarn.lock`, pins `packageManager: pnpm@…`, rewrites `npm` references in scripts, runs `pnpm install` to materialise `pnpm-lock.yaml`.                                                          |
+| 2    | `onboard`            | Installs `@reddoorla/maintenance` + the audit deps (`@lhci/cli`, `@playwright/test`, `@axe-core/playwright`) on the site. Pins the maintenance dep to a caret range against this package's own version at runtime.            |
+| 3    | `sync-configs`       | Writes the canonical config templates into the site (eslint, prettier, lighthouserc, playwright config, svelte config) and merges canonical entries into `.gitignore`.                                                        |
+| 4    | `svelte-codemods`    | Optional cleanup pass applying the Svelte 5 gotcha codemods (`export let` → `$props()`, `on:event` → `onevent`, `$:` → `$derived`/`$effect`, etc.) for sites that surface new strictness warnings after the original upgrade. |
+| 5    | `a11y-fixtures-page` | Writes a starter `src/routes/dev/a11y-fixtures/+page.svelte` if the route doesn't already exist. The hardcoded URL in `lighthouse` and `playwright-a11y` configs targets this route. Operator edits are never clobbered.      |
+| 6    | `audit`              | Runs `deps`, `lighthouse`, `a11y`, `security`, `lint` — see [Audits](#audits).                                                                                                                                                |
 
-Each recipe refuses to run on a dirty working tree, creates a fresh `maint/<recipe>-<UTC-ms-timestamp>` branch, and emits one or more atomic commits.
+Each recipe refuses to run on a dirty working tree, creates a fresh `maint/<recipe>-<UTC-ms-timestamp>` branch, and emits one or more atomic commits. Running individual steps standalone (e.g. `reddoor-maint sync-configs`) still works — `init` is for when you want the whole chain in one command.
 
 ---
 
@@ -37,6 +44,7 @@ Each recipe refuses to run on a dirty working tree, creates a fresh `maint/<reci
 reddoor-maint list-audits       # audit descriptions
 reddoor-maint list-recipes      # recipe descriptions
 
+reddoor-maint init [site]       # full onboarding chain (preferred entrypoint)
 reddoor-maint audit [site]      # run audits
 reddoor-maint sync-configs [site]
 reddoor-maint bump-deps [site]
@@ -72,11 +80,13 @@ Each recipe is `(site, opts?) => Promise<RecipeResult>` and is exported from the
 
 ```ts
 import {
+  init,
   syncConfigs,
   bumpDeps,
   onboard,
   convertToPnpm,
   svelteCodemods,
+  a11yFixturesPage,
   upgradeSvelte4to5,
 } from "@reddoorla/maintenance";
 ```
@@ -113,6 +123,14 @@ Standalone codemod pass for sites already on Svelte 5. Applies the same gotcha c
 
 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.
 
+### `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`
+
+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`.
+
 ---
 
 ## Audits
@@ -296,7 +314,60 @@ RESEND_WEBHOOK_SECRET=whsec_XXXX  # only for the deployed webhook
 
    Renders + sends every Reports row with `Draft ready=true && Approved to send=true && Sent at IS NULL`. Stamps `Sent at` + `Delivery status=pending` on each.
 
-5. **Delivery status updates automatically** via the Resend webhook (Netlify Function at `netlify/functions/resend-webhook.mts`) — `Delivery status` flips to `delivered` / `bounced` / `complained` as events arrive.
+5. **Delivery status updates automatically** via the Resend webhook (Netlify Function at `netlify/functions/resend-webhook.mts`) — `Delivery status` flips to `delivered` / `bounced` / `complained` as events arrive. Deploy procedure: see [Webhook deployment](#webhook-deployment-netlify--resend) below.
+
+### Webhook deployment (Netlify + Resend)
+
+The Resend delivery webhook lives at `netlify/functions/resend-webhook.mts` in this repo. Deploying it is a one-time operation per environment: connect the repo to a Netlify site, set three env vars, register the deployed URL with Resend.
+
+**1. Create the Netlify site:**
+
+- New site → Import from Git → pick `tucksravin/reddoor-maintenance`.
+- Branch to deploy: `main`. Build settings are read from [`netlify.toml`](netlify.toml) (no build command needed — functions-only).
+- Site name: pick something stable (e.g. `reddoor-webhooks`) since it ends up in the public webhook URL.
+
+**2. Set env vars** in Site settings → Environment variables:
+
+| Variable                | Value                                                                       |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `AIRTABLE_PAT`          | Same PAT used by the CLI (read+write on the Websites + Reports tables)      |
+| `AIRTABLE_BASE_ID`      | `appHG8nLOzULzXOER`                                                         |
+| `RESEND_WEBHOOK_SECRET` | Generated by Resend in step 4 — paste back here after creating the endpoint |
+
+**3. Trigger a deploy** (Deploys → Trigger deploy → Deploy site). When it goes green, curl the health endpoint:
+
+```bash
+curl https://<your-site>.netlify.app/.netlify/functions/resend-webhook
+```
+
+Expected:
+
+```json
+{
+  "status": "ok",
+  "service": "reddoor-resend-webhook",
+  "env": {
+    "RESEND_WEBHOOK_SECRET": true,
+    "AIRTABLE_PAT": true,
+    "AIRTABLE_BASE_ID": true
+  }
+}
+```
+
+Any `false` means the env var didn't land — re-check step 2 and re-deploy. The health endpoint reports presence-only and never returns secret values, so the output is safe to share in a support ticket.
+
+**4. Register the webhook in Resend:** [resend.com/webhooks](https://resend.com/webhooks) → Add Endpoint → paste the function URL from step 3 → select events `email.delivered`, `email.bounced`, `email.complained` → save. Copy the generated **Signing Secret** (`whsec_…`) into Netlify's `RESEND_WEBHOOK_SECRET` env var (step 2) and trigger another deploy so the secret takes effect.
+
+**5. End-to-end smoke test (using ERP Industrials):**
+
+```bash
+# from your CLI:
+reddoor-maint report erp-industrials   # drafts a Maintenance report → Airtable
+# approve the draft in Airtable, then:
+reddoor-maint report --send-ready
+```
+
+Within a few minutes, watch the ERP Reports row's `Delivery status` flip from `pending` → `delivered` as Resend pings the webhook. Function logs in Netlify show each event with its messageId + new status. If the webhook returns 5xx, svix retries; check the Netlify function log for the error envelope.
 
 ### Frequency math
 

package/dist/cli/bin.js

@@ -735,7 +735,7 @@ var init_orchestrate = __esm({
 });
 
 // src/cli/bin.ts
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { cac } from "cac";
 
@@ -744,7 +744,7 @@ import { resolve as resolve2 } from "path";
 
 // src/audits/util/spawn.ts
 import { spawn } from "child_process";
-var defaultSpawn = (cmd, args, opts = {}) => new Promise((resolve9, reject) => {
+var defaultSpawn = (cmd, args, opts = {}) => new Promise((resolve10, reject) => {
   const streaming = opts.streaming === true;
   const child = spawn(cmd, [...args], {
     cwd: opts.cwd,
@@ -767,7 +767,7 @@ var defaultSpawn = (cmd, args, opts = {}) => new Promise((resolve9, reject) => {
   });
   child.on("close", (code) => {
     if (timer) clearTimeout(timer);
-    resolve9({ code: code ?? -1, stdout, stderr });
+    resolve10({ code: code ?? -1, stdout, stderr });
   });
 });
 
@@ -3322,12 +3322,174 @@ async function runSingleSiteDraft(slug, opts) {
   return { output: `Draft created: ${result.reportRow?.reportId}`, code: 0 };
 }
 
+// src/cli/commands/init.ts
+import { resolve as resolve9 } from "path";
+
+// src/recipes/a11y-fixtures-page/index.ts
+import { access, mkdir as mkdir3, writeFile as writeFile10 } from "fs/promises";
+import { dirname as dirname4, join as join22 } from "path";
+
+// src/recipes/a11y-fixtures-page/template.ts
+var A11Y_FIXTURES_PAGE_RELATIVE = "src/routes/dev/a11y-fixtures/+page.svelte";
+var A11Y_FIXTURES_PAGE_TEMPLATE = `<svelte:head>
+  <title>a11y fixtures \u2014 Reddoor</title>
+  <meta
+    name="description"
+    content="Reddoor accessibility fixtures \u2014 semantic landmarks, heading hierarchy, and a stable target for @lhci/cli and Playwright + axe-core coverage. Not linked from the public site."
+  />
+</svelte:head>
+
+<main>
+  <header>
+    <h1>Accessibility fixtures</h1>
+    <p>
+      This page exists so <code>@lhci/cli</code> and Playwright + axe-core have a
+      stable target with predictable a11y characteristics. It is not linked from
+      the public site.
+    </p>
+  </header>
+
+  <section aria-labelledby="landmarks-heading">
+    <h2 id="landmarks-heading">Landmarks</h2>
+    <p>
+      A single <code>main</code> wraps the page; sections each declare
+      <code>aria-labelledby</code> matched to their heading id so screen readers
+      and axe both see a clean outline.
+    </p>
+  </section>
+
+  <section aria-labelledby="links-heading">
+    <h2 id="links-heading">Links</h2>
+    <p>
+      <a href="/">Back to home</a> \u2014 relative link with descriptive visible text,
+      so no <code>aria-label</code> override is needed.
+    </p>
+  </section>
+</main>
+`;
+
+// src/recipes/a11y-fixtures-page/index.ts
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function a11yFixturesPage(site) {
+  const target = join22(site.path, A11Y_FIXTURES_PAGE_RELATIVE);
+  return withRecipe({
+    name: "a11y-fixtures-page",
+    site,
+    plan: async () => {
+      if (await fileExists(target)) {
+        return { kind: "noop", notes: `${A11Y_FIXTURES_PAGE_RELATIVE} already exists` };
+      }
+      return { kind: "apply", plan: { target } };
+    },
+    apply: async (planned, { commit: commit2 }) => {
+      await mkdir3(dirname4(planned.target), { recursive: true });
+      await writeFile10(planned.target, A11Y_FIXTURES_PAGE_TEMPLATE, "utf-8");
+      await commit2("feat: add /dev/a11y-fixtures starter route");
+      return { kind: "ok" };
+    }
+  });
+}
+
+// src/recipes/init.ts
+function recipeStep(name, fn) {
+  return {
+    name,
+    run: async (site) => ({ kind: "recipe", result: await fn(site) })
+  };
+}
+var DEFAULT_INIT_STEPS = [
+  recipeStep("convert-to-pnpm", convertToPnpm),
+  recipeStep("onboard", onboard),
+  recipeStep("sync-configs", syncConfigs),
+  recipeStep("svelte-codemods", svelteCodemods),
+  recipeStep("a11y-fixtures-page", a11yFixturesPage),
+  {
+    name: "audit",
+    run: async (site) => ({ kind: "audit", results: await runAudits(site) })
+  }
+];
+async function init(site, opts = {}) {
+  const steps = opts.steps ?? DEFAULT_INIT_STEPS;
+  const out = [];
+  for (const step of steps) {
+    let result;
+    try {
+      result = await step.run(site);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      out.push({ name: step.name, result: { kind: "error", message } });
+      return { site: siteLabel(site), steps: out, complete: false };
+    }
+    out.push({ name: step.name, result });
+    if (result.kind === "recipe" && result.result.status === "failed") {
+      return { site: siteLabel(site), steps: out, complete: false };
+    }
+  }
+  return { site: siteLabel(site), steps: out, complete: true };
+}
+
+// src/cli/commands/init.ts
+function formatStep(name, r) {
+  if (r.kind === "error") return `${name.padEnd(20)} error: ${r.message}`;
+  if (r.kind === "audit") {
+    const lines = r.results.map(
+      (a) => `  ${a.audit.padEnd(12)} ${a.status.padEnd(5)} ${a.summary}`
+    );
+    return `${name.padEnd(20)} ${r.results.length} audit(s):
+${lines.join("\n")}`;
+  }
+  const rec = r.result;
+  if (rec.status === "noop") return `${name.padEnd(20)} noop${rec.notes ? ` \u2014 ${rec.notes}` : ""}`;
+  if (rec.status === "failed")
+    return `${name.padEnd(20)} failed${rec.notes ? ` \u2014 ${rec.notes}` : ""}`;
+  return `${name.padEnd(20)} applied (${rec.commits.length} commit${rec.commits.length === 1 ? "" : "s"})${rec.notes ? ` \u2014 ${rec.notes}` : ""}`;
+}
+function formatResult7(r) {
+  const header = `[${r.site}] init \u2014 ${r.complete ? "complete" : "STOPPED"}`;
+  const body = r.steps.map((s) => formatStep(s.name, s.result)).join("\n");
+  return `${header}
+${body}`;
+}
+function exitCodeFor(r) {
+  if (!r.complete) return 1;
+  for (const step of r.steps) {
+    if (step.result.kind === "audit" && step.result.results.some((a) => a.status === "fail")) {
+      return 1;
+    }
+  }
+  return 0;
+}
+async function runInitCommand(site, opts) {
+  const cwd = opts.cwd ? resolve9(opts.cwd) : process.cwd();
+  let sites = await resolveSites({
+    ...site !== void 0 ? { site } : {},
+    ...opts.fleet !== void 0 ? { fleet: opts.fleet } : {},
+    cwd
+  });
+  if (opts.fleet) {
+    const workdir = opts.workdir ?? `${process.env.HOME ?? ""}/.reddoor-maint/sites`;
+    sites = await Promise.all(sites.map((s) => cloneIfNeeded(s, { workdir })));
+  }
+  const results = [];
+  for (const s of sites) results.push(await init(s));
+  const output = results.map(formatResult7).join("\n\n");
+  const code = results.some((r) => exitCodeFor(r) !== 0) ? 1 : 0;
+  return { output, code };
+}
+
 // src/cli/version.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { join as join22 } from "path";
+import { join as join23 } from "path";
 function resolvePackageVersion(fromDir) {
   try {
-    const raw = readFileSync2(join22(fromDir, "..", "..", "package.json"), "utf-8");
+    const raw = readFileSync2(join23(fromDir, "..", "..", "package.json"), "utf-8");
     const pkg = JSON.parse(raw);
     return pkg.version ?? "unknown";
   } catch {
@@ -3336,7 +3498,7 @@ function resolvePackageVersion(fromDir) {
 }
 
 // src/cli/bin.ts
-var here2 = dirname4(fileURLToPath3(import.meta.url));
+var here2 = dirname5(fileURLToPath3(import.meta.url));
 var version = resolvePackageVersion(here2);
 var AUDIT_DESCRIPTIONS = {
   deps: "Diff site package.json against the bundled baseline version map.",
@@ -3351,7 +3513,9 @@ var RECIPE_DESCRIPTIONS = {
   "svelte-4-to-5": "Run the 7-commit Svelte 4 \u2192 5 upgrade recipe.",
   "svelte-codemods": "Apply Svelte 5 gotcha codemods to an already-migrated site (state_referenced_locally, etc.).",
   "convert-to-pnpm": "Convert an npm/yarn site to pnpm (lockfile, packageManager, scripts).",
-  onboard: "Install @reddoorla/maintenance + audit deps on a site (preferred first step)."
+  onboard: "Install @reddoorla/maintenance + audit deps on a site (preferred first step).",
+  "a11y-fixtures-page": "Write src/routes/dev/a11y-fixtures/+page.svelte (stub for lhci + axe targets).",
+  init: "Run the full onboarding chain (convert-to-pnpm \u2192 onboard \u2192 sync-configs \u2192 svelte-codemods \u2192 a11y-fixtures-page \u2192 audit)."
 };
 async function runOrExit(fn, opts) {
   try {
@@ -3428,6 +3592,15 @@ cli.command(
 ).option("--workdir <path>", "Clone target for fleet mode (default ~/.reddoor-maint/sites)").action(
   async (site, opts) => runOrExit(() => runOnboardCommand(site, opts), opts)
 );
+cli.command(
+  "init [site]",
+  "One-shot guided onboarding: convert-to-pnpm \u2192 onboard \u2192 sync-configs \u2192 svelte-codemods \u2192 a11y-fixtures-page \u2192 audit."
+).option(
+  "--fleet <inventory>",
+  'Inventory file (.json or .mjs/.js), or "airtable" to read from Websites table'
+).option("--workdir <path>", "Clone target for fleet mode (default ~/.reddoor-maint/sites)").action(
+  async (site, opts) => runOrExit(() => runInitCommand(site, opts), opts)
+);
 cli.command("report [site]", "Draft or send maintenance/testing reports.").option("--due", "Scan all Websites and draft overdue reports.").option(
   "--preview",
   "Single-site dry run; writes reports/<slug>/draft.html, never touches Airtable."