@rm-industries/create-forge 0.3.0-alpha.0 → 0.4.0-beta.1

package/dist/template/README.md

@@ -11,30 +11,129 @@ The template's `.editorconfig` shares UTF-8, LF, final-newline, two-space, and
 120-column settings with supported editors and Oxfmt. `oxfmt.config.ts` contains
 only formatter-specific behavior such as quote and import ordering.
 
-| Command                 | Purpose                                                                     |
-| ----------------------- | --------------------------------------------------------------------------- |
-| `npm run dev`           | Start Astro's local development server.                                     |
-| `npm run build`         | Create the production site in `dist/`.                                      |
-| `npm run preview`       | Serve the production build locally. Run `build` first.                      |
-| `npm run typecheck`     | Generate Astro types and run TypeScript without emitting files.             |
-| `npm run astro:check`   | Validate Astro components, content, and diagnostics.                        |
-| `npm run format`        | Check formatting with Oxfmt.                                                |
-| `npm run format:fix`    | Apply Oxfmt formatting.                                                     |
-| `npm run lint`          | Run code, CSS, Markdown, and spelling checks.                               |
-| `npm run lint:code`     | Check JavaScript and TypeScript with Oxlint.                                |
-| `npm run lint:css`      | Check CSS with Stylelint.                                                   |
-| `npm run lint:markdown` | Check Markdown with Markdownlint.                                           |
-| `npm run spellcheck`    | Check repository text with cspell.                                          |
-| `npm test`              | Run TypeScript unit tests with Vitest.                                      |
-| `npm run test:e2e`      | Run browser and accessibility tests with Playwright.                        |
-| `npm run audit`         | Report high-severity dependency vulnerabilities with npm.                   |
-| `npm run quality`       | Run the deterministic formatting, linting, type, unit-test, and build gate. |
+| Command                  | Purpose                                                          |
+| ------------------------ | ---------------------------------------------------------------- |
+| `npm run dev`            | Start Astro's local development server.                          |
+| `npm run build`          | Create the production site in `dist/`.                           |
+| `npm run validate:build` | Validate required output and scan generated text.                |
+| `npm run preview`        | Serve the production build locally. Run `build` first.           |
+| `npm run typecheck`      | Generate Astro types and run TypeScript without emitting files.  |
+| `npm run astro:check`    | Validate Astro components, content, and diagnostics.             |
+| `npm run format`         | Check formatting with Oxfmt.                                     |
+| `npm run format:fix`     | Apply Oxfmt formatting.                                          |
+| `npm run lint`           | Run code, CSS, Markdown, and spelling checks.                    |
+| `npm run lint:code`      | Check JavaScript and TypeScript with Oxlint.                     |
+| `npm run lint:css`       | Check CSS with Stylelint.                                        |
+| `npm run lint:markdown`  | Check Markdown with Markdownlint.                                |
+| `npm run spellcheck`     | Check repository text with cspell.                               |
+| `npm run audit:unused`   | Detect unused files, exports, and dependencies with Knip.        |
+| `npm run lighthouse:ci`  | Build and enforce Lighthouse scores and transfer budgets.        |
+| `npm test`               | Run the `test:unit` command.                                     |
+| `npm run test:unit`      | Run deterministic TypeScript unit tests with Vitest.             |
+| `npm run test:a11y`      | Run focused Playwright and axe accessibility checks.             |
+| `npm run test:coverage`  | Run unit tests and enforce V8 coverage thresholds.               |
+| `npm run test:e2e`       | Run browser and accessibility tests with Playwright.             |
+| `npm run audit`          | Reject unapproved high-severity dependency vulnerabilities.      |
+| `npm run quality:static` | Run every static-quality and dependency audit.                   |
+| `npm run quality:core`   | Run static checks, coverage tests, build, and output validation. |
+| `npm run quality`        | Run the complete generated-project quality pipeline.             |
 
 During development, run `npm run dev`. Before committing, run
-`npm run quality` and `npm run test:e2e`. Run `npm run audit` separately because
-it queries the npm registry and its result can change without a source change.
-The quality command remains deterministic and suitable for offline work after
-dependencies are installed.
+`npm run quality`. It runs static validation and dependency auditing, unit tests
+with coverage thresholds, a production build and generated-output validation,
+the complete Playwright and axe suite, and Lighthouse budgets in that order.
+Each stage is joined with `&&`, so the command stops immediately and returns a
+non-zero status when any stage fails. Browser tests and Lighthouse start from
+their own production build so they remain independently runnable and cannot
+accidentally inspect stale output.
+
+The complete command is intentionally high cost. Use `npm run quality:static`
+for the quickest source-only feedback or `npm run quality:core` for every check
+that does not launch a browser. Both commands include `npm run audit`, so they
+query the npm registry and can change when new advisories are published. Run
+the individual scripts when working offline. CI may execute independent stages
+in parallel, but a project generated by the packed Forge initializer must pass
+the documented `npm run quality` command as a single ordered pipeline.
+
+## Continuous integration
+
+The generated `.github/workflows/project.yml` runs on pull requests targeting
+`main` and on pushes to `main`. It separates static quality, coverage-enforced
+unit tests, the validated production build, browser and accessibility tests,
+and Lighthouse budgets so failures identify the affected gate directly. The
+required `Project` result succeeds only after every release-blocking job passes.
+
+The workflow installs dependencies with `npm ci`, caches npm downloads using
+the lockfile, cancels superseded runs on the same Git reference, and grants only
+read access to repository contents. Pull requests receive no secrets or write
+permissions. Coverage, production builds, Lighthouse reports, and browser
+failure evidence are retained for seven days. All third-party actions use
+immutable commit pins.
+
+Security automation is included alongside project CI. CodeQL analyzes the
+project's TypeScript and GitHub Actions on pull requests, pushes to `main`, and
+a weekly schedule. Dependency review rejects pull requests that introduce
+known high- or critical-severity vulnerabilities. A separate scheduled
+automation workflow validates workflow syntax and scans GitHub Actions with
+Zizmor. Zizmor uploads its findings to GitHub code scanning for review in the
+Security tab without failing the workflow solely because it found an issue.
+The job receives `security-events: write` only for that upload; all other access
+remains read-only. Repositories can make selected code-scanning severities
+merge-blocking later through their ruleset without changing the workflow.
+
+Dependabot checks npm and GitHub Actions weekly. Minor and patch npm updates are
+grouped by production or development scope, while major updates remain separate
+for deliberate review. Updates use cooldown periods to avoid adopting newly
+released versions immediately. Because pre-1.0 Sveltia minor releases may be
+breaking, `@sveltia/cms` updates are kept separate from generic production
+dependency groups. Its pull requests must satisfy the compatibility line
+declared by `@rm-industries/content-model`; moving to a later minor requires a
+tested content-model release first. No version is ignored, security updates
+remain enabled, and every update must pass the complete project and security
+workflows before merging.
+
+GitHub chooses the Dependabot run times, distributing update checks across its
+available schedule. Forge derives distinct weekly CodeQL and workflow-validation
+minutes from the generated package name. This keeps generation reproducible
+while preventing every Forge project from starting scheduled work simultaneously.
+
+Playwright builds the site and runs Chromium against Astro's production preview,
+not the development server. Its browser coverage exercises desktop and mobile
+navigation, article listing/detail flows, article pagination, light and dark
+themes, keyboard use, missing-page recovery, metadata, supporting site files,
+and content-manager startup. Each test receives a fresh browser context, and
+tests use accessible roles and names where the rendered interface provides
+them. On failure, Playwright retains screenshots and traces in `test-results/`;
+the HTML report is written to `playwright-report/`. CI retains both directories
+for seven days, including failed runs.
+
+Accessibility verification combines automation with the dated manual review in
+`docs/accessibility-checklist.md`. Repeat that checklist after changing content,
+navigation, themes, components, or interactive behavior; automated axe checks
+cannot judge every aspect of reading order, language, focus order, contrast, or
+alternative-text quality.
+
+Lighthouse CI runs three times each against the production home, article
+listing, and article detail pages, then enforces median category scores and
+transfer budgets. The measured baseline, headroom, exclusions, and update rules
+are documented in `docs/performance-budget.md`. Reports are written to the
+generated `.lighthouseci/` directory; CI retains them for seven days even when
+an assertion fails.
+
+The configured exclusions cover only generated output, dependency directories,
+and tool artifacts. Stylelint's exceptions recognize Tailwind and DaisyUI
+directives used by `src/styles/global.css`; they do not suppress ordinary CSS
+rules. Knip uses its Astro integration without an ignore list, and Oxlint uses
+its recommended defaults without project-specific rule suppression.
+
+Vitest coverage includes configuration, shared content-model registration,
+Astro and Sveltia integration code, content utilities, URL helpers, theme
+configuration, and preview registration. Statements, branches, functions, and
+lines must remain at 100%. Add direct positive and negative tests when this
+source grows; do not lower thresholds or exclude source merely to make a change
+pass. HTML details are written to `coverage/`, which is generated and ignored.
+CI enforces the same thresholds and retains the HTML report for seven days,
+including when the coverage job fails.
 
 Edit `src/config/site.ts` to change the site name, description, author,
 canonical URL, repository, language, navigation, social links, and derived CMS branding. The Astro

package/dist/template/audit-ci.jsonc

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://github.com/IBM/audit-ci/raw/main/docs/schema.json",
+  "high": true,
+  "allowlist": [
+    {
+      "GHSA-jmr9-qjv8-65gv": {
+        "active": true,
+        "expiry": "2026-11-30",
+        "notes": "Lighthouse CI development-only browser download path; Forge uses the installed CI browser and does not extract attacker-provided archives.",
+      },
+    },
+    {
+      "GHSA-ph9p-34f9-6g65": {
+        "active": true,
+        "expiry": "2026-11-30",
+        "notes": "Lighthouse CI development-only temporary files use tool-controlled names and paths, not attacker-provided prefixes or postfixes.",
+      },
+    },
+  ],
+}

package/dist/template/cspell.config.ts

@@ -1,6 +1,23 @@
 import { defineConfig } from 'cspell';
 
 export default defineConfig({
-  ignorePaths: ['node_modules', 'dist', 'coverage', 'playwright-report', 'test-results'],
-  words: ['Catppuccin', 'contentinfo', 'daisyui', 'Fira', 'fontsource', 'Macchiato', 'prefersdark', 'Sveltia'],
+  // Ignore only installed dependencies and generated tool output.
+  ignorePaths: ['node_modules', 'dist', 'coverage', 'playwright-report', 'test-results', '.lighthouseci'],
+  words: [
+    'autorun',
+    'Catppuccin',
+    'contentinfo',
+    'daisyui',
+    'Fira',
+    'fontsource',
+    'GHSA',
+    'lhci',
+    'lighthouseci',
+    'Macchiato',
+    'prefersdark',
+    'Sveltia',
+    'unreviewed',
+    'WCAG',
+    'Zizmor',
+  ],
 });

package/dist/template/docs/accessibility-checklist.md

@@ -0,0 +1,50 @@
+# Accessibility review checklist
+
+This checklist records the manual accessibility review of the unmodified Forge
+template. Generated-project maintainers must repeat it after changing content,
+navigation, themes, components, or interactive behavior; replace the review
+record below with their own date, environment, results, and linked issues.
+
+## Baseline review
+
+- **Date:** 2026-08-30
+- **Environment:** Chromium via Playwright 1.62.1 against the production preview
+- **Viewport coverage:** desktop and 320 × 640 mobile
+- **Input:** keyboard and pointer
+- **Result:** passed without a release-blocking accessibility issue
+
+## Manual checks
+
+- [x] Keyboard order starts with the skip link and then follows the visible
+      page order without trapping focus.
+- [x] Every interactive element displays a visible focus indicator in light
+      and dark modes.
+- [x] Activating **Skip to content** moves focus to the single main landmark.
+- [x] Text, controls, focus indicators, and linked text remain distinguishable
+      in the default Latte and Mocha themes.
+- [x] Reduced-motion preference removes smooth scrolling and shortens CSS
+      animations and transitions.
+- [x] Representative pages contain one descriptive level-one heading and do
+      not skip heading levels.
+- [x] Public pages expose a banner, named primary navigation, one main landmark,
+      and a content information landmark.
+- [x] Desktop and mobile navigation remain operable using only the keyboard.
+- [x] The custom 404 page identifies the error and provides a clear route home.
+
+The content manager startup and no-index policy are tested separately. Its
+editor interface is supplied by the pinned Sveltia dependency and is outside
+this public-site audit; evaluate that third-party UI against the needs of the
+project's editors before deployment.
+
+## Automated companion checks
+
+Run `npm run test:a11y` after each manual review. The suite applies axe-core's
+WCAG 2.0, 2.1, and 2.2 A/AA rules to representative public routes in both
+default color schemes. It also asserts landmarks, level-one headings, skip-link
+behavior, responsive overflow, current-page navigation, and reduced motion.
+Serious or critical axe violations block the browser-test job.
+
+Automated checks do not replace judgment about reading order, wording, focus
+order, contrast in newly introduced states, or whether alternative text conveys
+the intended meaning. Record any failure as a linked release-blocking issue
+rather than checking off an unverified item.

package/dist/template/docs/performance-budget.md

@@ -0,0 +1,68 @@
+# Lighthouse performance budget
+
+Lighthouse CI protects the generated site's public-page baseline. Run
+`npm run lighthouse:ci` after changes that can affect rendering, assets,
+metadata, or client behavior. The command builds the production site, collects
+three reports per route, and evaluates the median result.
+
+## Enforced routes
+
+- `/` represents the landing-page layout and card content.
+- `/articles/` represents a content collection and repeated cards.
+- `/articles/designing-a-calm-starting-point/` represents rendered Markdown,
+  typography, tags, and article pagination.
+
+The about and custom 404 pages reuse the same public layout with smaller or
+equivalent resource profiles and remain covered by browser and accessibility
+tests. The `/admin/` route is intentionally excluded: it loads the pinned
+third-party Sveltia editor application and is not representative of public
+visitor performance. Reassess that editor separately before deploying it for a
+specific team.
+
+## Category thresholds
+
+| Category       | Minimum |
+| -------------- | ------: |
+| Performance    |      90 |
+| Accessibility  |     100 |
+| Best practices |      95 |
+| SEO            |      95 |
+
+Accessibility remains at 100 because FGE-063 separately enforces serious and
+critical axe findings. The other thresholds allow ordinary Lighthouse runtime
+variance while still failing a meaningful regression.
+
+## Transfer budgets
+
+| Resource | Maximum bytes | Rationale                                                           |
+| -------- | ------------: | ------------------------------------------------------------------- |
+| Script   |             0 | The public template ships no client JavaScript.                     |
+| Total    |       125,000 | Approximately 24% headroom above the measured 100,675-byte maximum. |
+
+The 2026-08-30 baseline used Lighthouse 12.6.1 and three local Chromium runs per
+route. Every run scored 99 performance and 100 for accessibility, best
+practices, and SEO. Script transfer was zero bytes. Total transfer was stable at
+100,675 bytes for home, 100,447 bytes for the listing, and 100,498 bytes for the
+article detail.
+
+The total budget leaves room for minor generated-content and toolchain variance
+without allowing an unreviewed asset or client bundle. Do not raise a threshold
+or exclude a route merely to make CI pass. If a product requirement deliberately
+changes the budget, record the new three-run measurements, explain the user
+benefit and cost, and review the change in its pull request.
+
+## Dependency note
+
+`@lhci/cli` 0.15.1 pins Lighthouse 12.6.1. Forge keeps that upstream-tested
+dependency graph instead of overriding Lighthouse or its transitive
+dependencies independently. Upgrade the top-level Lighthouse CI package when a
+release supports a newer Lighthouse runtime, then repeat the three-run
+collection and assertion compatibility checks.
+
+The pinned graph currently includes high-severity `extract-zip` and `tmp`
+advisories. Both are confined to development-only Lighthouse tooling:
+Lighthouse uses the installed browser rather than extracting an
+attacker-provided browser archive, and its temporary paths are tool-controlled.
+`audit-ci.jsonc` records narrow, expiring exceptions for those two advisory IDs.
+All other high or critical advisories still fail `npm run audit`. Review or
+remove the exceptions by 2026-11-30 rather than extending them automatically.