@getvitops/utils 8.2.0 → 8.3.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @getvitops/utils
 
+## 8.3.0-alpha.0
+
+### Minor Changes
+
+- 161c7f3: A contact form that works end to end: `vitops setup turnstile`, `<wc-turnstile>`, the `vitops.form` EmDash block, and the route the emdash template ships to receive it.
+
+  **CSS, all formats** (no existing class changes): `forms.css` gains `.form-notice--target:not(:target)` (a message revealed only when the URL fragment names it, which is how a prerendered page shows a no-JS form's result) and `:where(wc-turnstile) { display: block }`.
+
+  **`@getvitops/core`:** new `<wc-turnstile sitekey="…">` in `elements.js`. It loads Cloudflare Turnstile on the first interaction with its form (no request to `challenges.cloudflare.com` for a visitor who only reads the page), holds an early submit until the token arrives, and leaves its slotted no-JS explanation in place until JS takes over. Turnstile is category `necessary`, so it is not behind the consent banner.
+
+  **`@getvitops/utils` / `@getvitops/cli`:** new `@getvitops/utils/turnstile` and `vitops setup turnstile [--dry] [--check] [--no-write] [--no-secret]`. It plans from the site's hostnames, creates a managed widget unless one already covers them (an existing widget is adopted, never edited, rotated or deleted), writes the public key to `site.security.turnstile.siteKey`, and pipes the one-time secret to `wrangler secret put VITOPS_TURNSTILE_SECRET` without writing it to any file. Needs `CLOUDFLARE_API_TOKEN` with **Account > Turnstile > Edit** and `CLOUDFLARE_ACCOUNT_ID`.
+
+  **`@getvitops/astro`:** `virtual:getvitops/head` gains `turnstileSiteKey` (read from `site.security.turnstile.siteKey`) so blocks can render the widget. No other change.
+
+  **`@getvitops/generator`:** `TIERS` gains a `turnstile` entry (wc-turnstile, claimed by `vitops.form`); `wc-multi-field`'s `emdashExempt` reason is reworded now the form block exists.
+
+  **`@getvitops/emdash`:** new `vitops.form` block: a field repeater (text, email, phone, long text, choose one, tick box), required flags, help text, success/error messages, optional Turnstile. It renders a semantic `<form method="post">` that works with no JavaScript, with a honeypot named per `createConversionRoute`'s defaults. A field named `phone` submits as `tel`, because the route reserves `phone` and `event`.
+
+  **`@getvitops/create`:** the emdash template ships `src/pages/api/track.ts` (`prerender = false`, `createConversionRoute()`), a seeded contact form, and `challenges.cloudflare.com` in both templates' Report-Only CSP (`script-src`, `frame-src`). The route refuses a post with nowhere to deliver and fails closed when a site key exists without `VITOPS_TURNSTILE_SECRET`. SETUP.html gains the Turnstile step. Existing sites: copy the route and the CSP change, then run `vitops setup turnstile`.
+
+- 175d16e: **Added: `vitops.reviews` and `vitops.nav` EmDash blocks.** Non-breaking.
+
+  - **`vitops.reviews`** renders Google reviews from the committed `.vitops/reviews.json` cache (`vitops reviews`) as a grid, carousel or marquee of `<ReviewCard>`. Fields: location key, layout, columns, limit, lowest rating, order, featured ids, reviewer photos (off by default), tone/colour. Which reviews show is `selectReviews()`, the one shared decision. Review JSON-LD is not offered (Google treats self-marked-up reviews as ineligible for rich results). A new review reaches the page after `vitops reviews` is re-run, committed and the site rebuilt, not when an editor saves; with no cache file the block renders nothing (a note in `astro dev`).
+  - **`vitops.nav`** renders a named EmDash menu inside page content (site map, section links, footer-style columns), never the header. Fields: menu (picked from the site's menus via a new `menus/list` plugin route, with `footer-sitemap`/`footer-legal`/`primary` as the static fallback), accessible name, visible heading and level, layout `list | inline | columns | sitenav`, depth 1-3, tone/colour. It is a `<nav>` with a name that is never `Primary`, `Site map` or `Legal` (the layout's landmarks), `aria-current="page"`, no runtime JS; a missing or empty menu renders nothing.
+  - `@getvitops/astro`: **`virtual:getvitops/reviews`**, served by `vitops()`, is `.vitops/reviews.json` as a build-time import (an empty cache when absent or unreadable), because a Worker cannot read the file. `<ReviewCard>` now renders the review's source link (`.review__source`, `rel="nofollow noopener noreferrer"`), which the pattern already styled. **Fix:** `src/json-ld.ts` was missing from the published `files`, so any consumer importing `<ReviewCard>` (which composes `schemas/Review.astro`) failed to build with an unresolved import. `@getvitops/emdash` now needs this version of `@getvitops/astro` for the `vitops.reviews` block.
+  - `@getvitops/utils`: new Worker-safe subpath **`@getvitops/utils/reviews/select`** (`selectReviews` and the review types, no `node:fs`). `selectReviews` now takes only the display fields (`featured`, `minRating`, `limit`, `sort`), so a caller with no configured `locationId` can use it; existing calls are unchanged.
+  - `@getvitops/core`: new `.navlist` pattern in `patterns/sitenav.css` (`.navlist`, `__item`, `__link`, `__label`, `__sub`, `--inline`, `--columns`). **All formats** (css, bricks, tailwind). No existing class changes.
+  - `@getvitops/generator`: `TIERS.review` lists `vitops.reviews` and `TIERS.sitenav` lists `vitops.nav` (and `.navlist`), so `vitops docs components` and the docsite show them.
+
+- 83d6f3c: Theming escape hatches, so a real palette builds without raw ramp steps. All additive; existing configs build unchanged.
+
+  - **Dark-only sites.** `designSystem.defaultColorScheme: "dark"` (accepted by the schema before, but ignored) now makes the dark tokens the `:root` appearance with `color-scheme: dark`, emits no light block or `data-theme` flip, and skips light-mode contrast checks. Reaches css, bricks and tailwind formats. Do not ship `<wc-color-scheme-toggle>` on such a site.
+  - **Role solid step and foreground.** `colors.roles.<role>` may be `{ hue, kind?, solid?, foreground? }`. `solid: 400` starts the solid family at step 400 (bold and x-bold walk one and two rungs darker); `foreground: "dark" | "light"` pins `text-on-<role>`. The APCA check (Lc 60) still runs on the pair emitted. The string shorthand is unchanged. All formats. The live editor's `roleTokens` still assume the default 600 family when re-pointing a role.
+  - **Split shadows.** `shadows.<name>` may be `{ box?, drop? }`: `box` (spread, inset, layers) is `--shadow-<name>`; `drop` is `--shadow-<name>-drop` and feeds `.drop-shadow-<name>` and the `shadow:` state shortcut. The string form is unchanged. css/bricks emit `.drop-shadow-*`; tailwind emits the `-drop` token only.
+  - **Layout tokens.** New optional `layout` block (`widths.{measure,breakout,spotlight,nav}`, `regionSpace.{min,preferred,max}`) emitted as `--width-*` / `--region-space*` on `:root` in css, bricks and tailwind formats, and exposed in `design-manifest.json` (`layout`, `reverseIndex`). Keys you omit keep the framework defaults.
+  - **`acknowledgeOffLadder: true`** on a palette hue silences that hue's off-ladder anchor warnings.
+  - **Typography:** `transform` and `decoration` are now accepted as aliases of `text-transform` and `text-decoration` (canonical wins when both are present) instead of warning and being dropped.
+  - **Docs strings** (`authoring.md`, JSON Schema hovers) state the Lc 60 muted-text requirement against the page plane and give a type-scale recipe for marketing headings.
+  - `@getvitops/utils`: `pickOn` takes an optional `prefer: 'light' | 'dark'`.
+
+- b47df4d: **Added: `vitops audit` — Lighthouse + axe budgets over a built site.** Non-breaking, opt-in.
+
+  `vitops audit [--build] [--url <base>] [--pages /a,/b] [--warn] [--out <dir>]` serves the existing build with `astro preview` on a dedicated port (4398; it aborts rather than attach to something else already there), audits `/` plus `/privacy`, `/terms`, `/cookies`, `/contact` and every link in `seed/seed.json`'s `primary*`/`footer*` menus, and skips any route that 404s (a 404 on `/` fails the run). Per page it runs axe (tags wcag2a, wcag2aa, wcag21a, wcag21aa) and Lighthouse on the same Chromium. Default budgets: LCP < 2500 ms, CLS < 0.1, TBT < 200 ms (the INP proxy), no serious or critical axe violations; override with `--lcp`, `--cls`, `--tbt`, `--impact`. Writes `report.json`, `report.md` and `pages/<page>.{json,md}` to `.vitops/audit/`; exits non-zero on failure unless `--warn`. Every report states that a pass is **not** AODA certification and lists the manual checks.
+
+  `playwright`, `@axe-core/playwright` and `lighthouse` are **optional peer dependencies** of `@getvitops/utils`, loaded lazily — nothing is installed or loaded unless you run the command, and a missing one fails with the install command. Pure planner and report rendering are `@getvitops/utils/audit` (new subpath).
+
+  CI: the reusable `site-ci.yml` gains opt-in `run-audit` (default `false`) and `audit-args` inputs; callers pinned to `@v1` that pass neither are unaffected.
+
+### Patch Changes
+
+- @getvitops/config@8.3.0-alpha.0
+
 ## 8.2.0
 
 ### Minor Changes

package/dist/audit/index.d.mts

@@ -0,0 +1,180 @@
+/** Shapes shared by the audit planner, the executor and the report renderers. */
+type AxeImpact = 'minor' | 'moderate' | 'serious' | 'critical';
+interface AuditBudgets {
+  /** Largest Contentful Paint ceiling, ms. */
+  lcpMs: number;
+  /** Cumulative Layout Shift ceiling (unitless). */
+  cls: number;
+  /** Total Blocking Time ceiling, ms — the lab proxy for INP. */
+  tbtMs: number;
+  /** axe impacts that fail the page. Default: serious + critical. */
+  blockingImpacts: AxeImpact[];
+}
+interface AxeViolation {
+  id: string;
+  /** axe reports `null` impact for some incomplete rules; normalised to `moderate`. */
+  impact: AxeImpact;
+  help: string;
+  helpUrl: string;
+  /** Total nodes the rule failed on. */
+  nodeCount: number;
+  /** First few CSS selectors, for the report. */
+  targets: string[];
+}
+interface PageMetrics {
+  /** `undefined` when Lighthouse could not compute it — which fails the page, not passes it. */
+  lcpMs?: number | undefined;
+  cls?: number | undefined;
+  tbtMs?: number | undefined;
+  /** Lighthouse category scores, 0-100. */
+  scores: {
+    performance?: number | undefined;
+    seo?: number | undefined;
+    bestPractices?: number | undefined;
+  };
+}
+interface BudgetFailure {
+  kind: 'lcp' | 'cls' | 'tbt' | 'axe' | 'metric-missing' | 'page-error' | 'required-page-missing';
+  message: string;
+}
+type PageStatus = 'audited' | 'skipped' | 'error';
+interface PageResult {
+  path: string;
+  url: string;
+  status: PageStatus;
+  httpStatus?: number;
+  /** Why a page was skipped or errored. */
+  reason?: string;
+  metrics?: PageMetrics;
+  violations?: AxeViolation[];
+  failures: BudgetFailure[];
+}
+type FormFactor = 'mobile' | 'desktop';
+interface AuditReport {
+  generatedAt: string;
+  baseUrl: string;
+  formFactor: FormFactor;
+  budgets: AuditBudgets;
+  axeTags: string[];
+  pages: PageResult[];
+  /** True when no page has a failure. */
+  passed: boolean;
+  /** Always present: what a pass does and does not mean. */
+  disclaimer: string;
+  manualChecks: string[];
+}
+export declare const DEFAULT_BUDGETS: AuditBudgets;
+/**
+ * `wcag2a`/`wcag2aa` are what AODA (WCAG 2.0 AA) asks for; `wcag21a`/`wcag21aa` add the
+ * 2.1 criteria we target. `wcag21aa` alone covers only the *new AA* criteria, not the
+ * new level-A ones, so both 2.1 tags are listed.
+ */
+export declare const AXE_TAGS: string[];
+/** Pages tried on every run. `/` is required; the rest are skipped when they 404. */
+export declare const DEFAULT_PAGES: string[];
+export declare const DISCLAIMER: string;
+export declare const MANUAL_CHECKS: string[];
+/**
+ * A menu-ish thing: EmDash seed (`items`), `getMenu()` (`items`, items with `children`),
+ * or either shape nested. Only `name`, `url` and children are read.
+ */
+interface MenuLike {
+  name?: string;
+  items?: MenuItemLike[];
+}
+interface MenuItemLike {
+  url?: string | null;
+  children?: MenuItemLike[];
+  items?: MenuItemLike[];
+}
+/**
+ * Normalise to a site-relative path, or `undefined` for anything that is not an
+ * auditable page of this site: external URLs, hash-only links, `mailto:`/`tel:`,
+ * protocol-relative URLs, file downloads (anything with an extension) and the CMS
+ * admin. Query and hash are dropped; a trailing slash is too (except the root).
+ */
+export declare function normalizePath(url: string | null | undefined): string | undefined;
+/** Is this one of the menus whose links are pages worth auditing? */
+export declare function isAuditMenu(name: string | undefined): boolean;
+/** Paths from the `primary*` / `footer*` menus (`footer-legal`, `primary-mobile`, …). */
+export declare function pathsFromMenus(menus: MenuLike[]): string[];
+/** Same, from an EmDash seed file's parsed JSON (`{ menus: [...] }`). */
+export declare function pathsFromSeed(seed: unknown): string[];
+interface PagePlanInput {
+  /** Paths found in menus. */
+  menuPaths?: string[];
+  /** Paths from `--pages`. */
+  extra?: string[];
+  /** Default true. `--no-defaults` for a site that wants an exact list. */
+  includeDefaults?: boolean;
+}
+/** The pages to try, `/` always first, unique, in a stable order. */
+export declare function planPages(input?: PagePlanInput): string[];
+/**
+ * What an HTTP status means for a candidate page. 404/410 → skipped (a single-page
+ * site has no `/contact`, and that is fine) — except `/`, which must exist. Any other
+ * non-2xx is an error: a 500 on `/privacy` is a defect, not an absent page.
+ */
+export declare function classifyStatus(path: string, httpStatus: number | undefined): {
+  status: 'audited' | 'skipped' | 'error';
+  reason?: string;
+};
+/** axe can report a null impact; treat it as `moderate`, never silently drop it. */
+export declare function normalizeImpact(impact: string | null | undefined): AxeImpact;
+/** `serious,critical` → impacts, rejecting typos so a budget cannot silently be empty. */
+export declare function parseImpacts(list: string): AxeImpact[];
+/** Everything that makes one audited page fail. Empty = the page passes. */
+export declare function evaluatePage(metrics: PageMetrics | undefined, violations: AxeViolation[] | undefined, budgets: AuditBudgets): BudgetFailure[];
+/** Build a `PageResult` for a page that was not audited (skipped or error). */
+export declare function unauditedPage(path: string, url: string, httpStatus: number | undefined, verdict: {
+  status: 'skipped' | 'error';
+  reason?: string;
+}): PageResult;
+export declare function auditedPage(path: string, url: string, httpStatus: number, metrics: PageMetrics, violations: AxeViolation[], budgets: AuditBudgets): PageResult;
+export declare function buildReport(input: {
+  generatedAt: string;
+  baseUrl: string;
+  formFactor: FormFactor;
+  budgets: AuditBudgets;
+  pages: PageResult[];
+}): AuditReport;
+/** `/` → `home`, `/a/b` → `a-b`: a safe per-page filename. */
+export declare function pageSlug(path: string): string;
+export declare function renderPageMarkdown(page: PageResult, budgets: AuditBudgets): string;
+export declare function renderMarkdown(report: AuditReport): string;
+/** Files to write, relative to the output dir: JSON + markdown overall and per page. */
+export declare function reportFiles(report: AuditReport): Record<string, string>;
+/** One-line-per-failure console summary. */
+export declare function formatSummary(report: AuditReport): string;
+/** A free TCP port, or `true` for "this specific one is free". */
+export declare function isPortFree(port: number): Promise<boolean>;
+/** Run a command to completion, inheriting stdio. Rejects on a non-zero exit. */
+export declare function runCommand(cmd: string, args: string[], cwd: string): Promise<void>;
+interface PreviewServer {
+  baseUrl: string;
+  stop(): void;
+}
+/**
+ * `astro preview` on a dedicated port.
+ *
+ * Astro's preview server silently moves to the next port when its own is taken, and
+ * a readiness probe would then happily attach to whatever owns the original one — the
+ * failure `site/playwright.config.ts` documents. So the port is checked free first and
+ * the run aborts if it is not.
+ */
+export declare function startPreview(opts: {
+  cwd: string;
+  port: number;
+  timeoutMs?: number;
+}): Promise<PreviewServer>;
+interface RunOptions {
+  baseUrl: string;
+  paths: string[];
+  budgets: AuditBudgets;
+  formFactor: FormFactor;
+  onProgress?: (message: string) => void;
+}
+/** Audit each path. Never throws for a bad PAGE — only for missing tooling/browser. */
+export declare function runAudit(opts: RunOptions): Promise<PageResult[]>;
+export type { AuditBudgets, AuditReport, AxeImpact, AxeViolation, BudgetFailure, FormFactor, MenuItemLike, MenuLike, PageMetrics, PagePlanInput, PageResult, PageStatus, PreviewServer, RunOptions };
+//# sourceMappingURL=index.d.mts.map

package/dist/audit/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/audit/types.ts","../../src/audit/plan.ts","../../src/audit/run.ts"],"mappings":";KAEY;UAEK;;EAEf;;EAEA;;EAEA;;EAEA,iBAAiB;;UAGF;EACf;;EAEA,QAAQ;EACR;EACA;;EAEA;;EAEA;;UAGe;;EAEf;EACA;EACA;;EAEA;IACE;IACA;IACA;;;UAIa;EACf;EACA;;KAGU;UAEK;EACf;EACA;EACA,QAAQ;EACR;;EAEA;EACA,UAAU;EACV,aAAa;EACb,UAAU;;KAGA;UAEK;EACf;EACA;EACA,YAAY;EACZ,SAAS;EACT;EACA,OAAO;;EAEP;;EAEA;EACA;;qBCrDW,iBAAiB;;;;;;qBAYjB;;qBAGA;qBAEA;qBAKA;;;;;UAgBI;EACf;EACA,QAAQ;;UAEO;EACf;EACA,WAAW;EACX,QAAQ;;;;;;;;wBASM,cAAc;;wBAsBd,YAAY;;wBAKZ,eAAe,OAAO;;wBAOtB,cAAc;UAKb;;EAEf;;EAEA;;EAEA;;;wBAIc,UAAU,QAAO;;;;;;wBAqBjB,eACd,cACA;EACG;EAAyC;;;wBAgB9B,gBAAgB,oCAAoC;;wBAKpD,aAAa,eAAe;;wBAe5B,aACd,SAAS,yBACT,YAAY,4BACZ,SAAS,eACR;;wBAyCa,cACd,cACA,aACA,gCACA;EAAW;EAA6B;IACvC;wBAmBa,YACd,cACA,aACA,oBACA,SAAS,aACT,YAAY,gBACZ,SAAS,eACR;wBAYa,YAAY;EAC1B;EACA;EACA,YAAY;EACZ,SAAS;EACT,OAAO;IACL;;wBAiBY,SAAS;wBAOT,mBAAmB,MAAM,YAAY,SAAS;wBAyC9C,eAAe,QAAQ;;wBAiCvB,YAAY,QAAQ,cAAc;;wBAgBlC,cAAc,QAAQ;;wBC3VtB,WAAW,eAAe;;wBAoB1B,WAAW,aAAa,gBAAgB,cAAc;UAUrD;EACf;EACA;;;;;;;;;;wBAWoB,aAAa;EACjC;EACA;EACA;IACE,QAAQ;UA+FK;EACf;EACA;EACA,SAAS;EACT,YAAY;EACZ,cAAc;;;wBAIM,SAAS,MAAM,aAAa,QAAQ"}