@meddleware/frontend-config 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.4] - 2026-11-07
+
+### Added
+
+- `mw-network-status`: writes the networks the platform is deployed on from the clients' deployment records, for the landing page, docs and developer docs.
+
+## [0.0.3] - 2026-11-07
+
+### Added
+
+- `mw-audit-gate`, `mw-third-party-licenses` and `mw-check-csp-inline`: the dependency-audit gate, the licence bundle and the inline-script
+  CSP check that every app repository carried as its own copy of a script.
+- `/csp`: `buildCsp`, `cspForProfile` and six named profiles that reproduce, byte for byte, the policies the app images served.
+- `meddlewareApp` (`/vite`), `vueTestConfig` (`/vitest`) and `tsconfig/vue-app.json`: the Vite, Vitest and TypeScript configuration that eleven
+  apps each repeated.
+- `mw-sync --check|--write` and `templates/`: the files that cannot be shared by reference stay identical across repositories, and the
+  Dockerfile's `ARG CSP` is held equal to the repository's profile.
+
 ## [0.0.2] - 2026-11-01
 
 ### Added

package/README.md

@@ -10,16 +10,23 @@ same accessibility and browser-support bar.
 | `/stylelint` | `stylelintConfig({ tokens?, compat?, browsers?, rules? })` — standard config, no hex, token-only colour and `z-index`, `@double-great/stylelint-a11y`, `stylelint-no-unsupported-browser-features`. |
 | `/html-validate` | `htmlValidateConfig({ elements?, rules? })` — recommended + `html-validate:a11y` + Vue, with `@meddleware/ui` components described as the native element they render. |
 | `/postcss` | Autoprefixer for the repo's browserslist. |
-| `/vite` | `viteTarget()` — Vite `build.target` derived from the browserslist; `themeInit({ default })` — a Vite plugin that loads ui's `theme-init.js` first in `<head>` (the saved or default colour mode and the season applied before first paint, no inline script, no CSP hash) and adds `color-scheme` and the browser-chrome `theme-color` from the tokens. |
+| `/vite` | `viteTarget()` — Vite `build.target` derived from the browserslist; `meddlewareApp({ plugins, theme?, wallet?, config? })` — the whole Vite configuration of a tool app (target, theme-init, e2e guard, wallet-adapter kept out of pre-bundling); `themeInit({ default })` — a Vite plugin that loads ui's `theme-init.js` first in `<head>` (the saved or default colour mode and the season applied before first paint, no inline script, no CSP hash) and adds `color-scheme` and the browser-chrome `theme-color` from the tokens. |
 | `/playwright` | `definePlaywrightConfig({ port, kind?, command?, browsers?, extra? })`. |
 | `/axe` | `expectAccessible(page, options)` — WCAG 2.2 AA gate; AAA as `aaa: 'gate'`, `'report'` or `'off'`. |
 | `/look` | `looks()`, `applyLook(page, theme, season)`, `offline(page)`, `VIEWPORTS`, `THEMES`, `SEASONS` — the viewport × colour mode × season matrix. |
 | `/shots` | `defineShots(states)` — one screenshot per state × look, for looking at the UI. |
 | `/a11y` | `defineA11ySuite(states, { aaa })` — the sweep every app runs, one call: each state in every colour mode × season at WCAG 2.2 AA and AAA, a 320 px reflow, 200% text size, forced colours, reduced motion and a keyboard pass. `expectNoHorizontalScroll`, `expectNoRunningAnimations` and `expectKeyboardFocusVisible` are exported on their own. |
-| `/vitest` | `inlineMeddleware` — the packages a test must process through Vite (they import `.css`/`.vue`), which also gives them the test's single copy of Vue; `installDialogShim()` — jsdom's missing `<dialog>` modality. |
+| `/vitest` | `vueTestConfig({ plugins, test? })` — the whole Vitest configuration of a Vue repository (jsdom, `tests/**/*.test.ts`, one copy of Vue, the UI packages processed through Vite); `inlineMeddleware` — those packages on their own; `installDialogShim()` — jsdom's missing `<dialog>` modality. |
 | `/bundle` + `check-prod-bundle` | `scanBundle(dist, { also })` and the `check-prod-bundle [dist] [--also TEXT]... [--also-regex PATTERN]...` command: fails when the e2e harness (the mock-wallet hooks, or an app's own stand-in marker) is found in a production build. Run it after the production build in CI and in the Dockerfile. |
 | `/wallet` | `connectMockWallet(page)`, `exposeSigner(page, signer)`, `E2E_ADDRESS` — the Playwright side of the mock wallet. |
 | `/lighthouserc` | `lighthouseConfig({ port, paths?, … })` — Lighthouse CI (accessibility must score 100). |
+| `/tsconfig/vue-app.json` | The compiler options of a Vue app (`"extends": "@meddleware/frontend-config/tsconfig/vue-app.json"`); the repository keeps only its `include`. |
+| `/csp` | `buildCsp(options)`, `cspForProfile(name, current?)`, `PROFILES`, `scriptHashesOf(csp)` — the Content-Security-Policy every app image serves, as six named profiles (`static`, `static-strict`, `console`, `chain`, `chain-wasm`, `docs`), so the policy is written once. |
+| `mw-sync` | `mw-sync --check` / `--write` in a repository root: the files every frontend repository copies (dependabot.yml, .dockerignore, postcss/stylelint configs, the Lighthouse allowlist) equal this package's `templates/`, and the Dockerfile's `ARG CSP` equals its profile. Declared in package.json: `"meddleware": { "kind": "app", "csp": "chain-wasm", "lhci": true }`. |
+| `mw-network-status` | `mw-network-status [--out src/network.json]`: which networks MeddleWare is deployed on, from the installed clients' deployment records through `networkAvailability` (`@meddleware/web-utils`). A static site runs it as `prebuild`, so "mainnet is coming" turns into "live" by the records alone. |
+| `mw-audit-gate` | CI dependency gate: `npm audit` at high/critical minus the dated, reasoned entries of `.github/audit-allowlist.json` (an entry with no reason or an expired date fails). |
+| `mw-third-party-licenses` | Writes `dist/THIRD_PARTY_LICENSES` from the lockfile's production packages and their installed licence texts; `--check` fails when none can be written. |
+| `mw-check-csp-inline` | `mw-check-csp-inline <policy or @Dockerfile> [dist]`: every inline script in the built pages is allowed by a `sha256` source in the policy, and the policy never allows `'unsafe-inline'` scripts. |
 
 ## Use
 

package/dist/audit-gate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/check-csp-inline.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/csp.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @param {CspOptions} options
+ * @returns {string}
+ */
+export function buildCsp(options?: CspOptions): string;
+/** The `'sha256-…'` hashes in a policy's script-src (kept when a profile such as `docs` is rebuilt). */
+export function scriptHashesOf(csp: string): string[];
+/** @param {string} name @param {string} [current] the policy now in the Dockerfile (its script hashes are kept) */
+export function cspForProfile(name: string, current?: string): string;
+/**
+ * @typedef {object} CspOptions
+ * @property {boolean} [wasm] allow WebAssembly (`'wasm-unsafe-eval'`): the Walrus and Move-bytecode clients
+ * @property {boolean} [chain] chain-facing app: https images, https connections (RPC, relay, aggregator and key-server hosts are partly configured), blob workers
+ * @property {boolean} [worker] allow `worker-src 'self' blob:` without the rest of `chain` (VitePress sites)
+ * @property {boolean} [strict] `base-uri` and `form-action` are `'none'` (a page with no forms and no `<base>`)
+ * @property {'self' | 'none'} [frameAncestors] who may frame the page (default `'self'`)
+ * @property {string[]} [scriptHashes] `'sha256-…'` sources for the inline scripts a static-site generator emits
+ */
+/** @type {Record<string, CspOptions>} */
+export const PROFILES: Record<string, CspOptions>;
+export type CspOptions = {
+    /**
+     * allow WebAssembly (`'wasm-unsafe-eval'`): the Walrus and Move-bytecode clients
+     */
+    wasm?: boolean | undefined;
+    /**
+     * chain-facing app: https images, https connections (RPC, relay, aggregator and key-server hosts are partly configured), blob workers
+     */
+    chain?: boolean | undefined;
+    /**
+     * allow `worker-src 'self' blob:` without the rest of `chain` (VitePress sites)
+     */
+    worker?: boolean | undefined;
+    /**
+     * `base-uri` and `form-action` are `'none'` (a page with no forms and no `<base>`)
+     */
+    strict?: boolean | undefined;
+    /**
+     * who may frame the page (default `'self'`)
+     */
+    frameAncestors?: "none" | "self" | undefined;
+    /**
+     * `'sha256-…'` sources for the inline scripts a static-site generator emits
+     */
+    scriptHashes?: string[] | undefined;
+};

package/dist/network-status.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * @param {{ networkAvailability: Function }} utils
+ * @param {Record<string, Record<string, unknown>>} records product name → its deployments object
+ */
+export function networkStatus(utils: {
+    networkAvailability: Function;
+}, records: Record<string, Record<string, unknown>>): any;

package/dist/sync.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * @param {string} root repository root
+ * @param {{ write?: boolean }} [options]
+ * @returns {{ file: string, ok: boolean, note: string }[]}
+ */
+export function sync(root: string, options?: {
+    write?: boolean;
+}): {
+    file: string;
+    ok: boolean;
+    note: string;
+}[];

package/dist/third-party-licenses.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/vite.d.ts

@@ -41,3 +41,28 @@ export function themeInit({ default: mode, scriptPath, colors }?: {
  * @param {Record<string, string | undefined>} env The environment (default: the process's).
  */
 export function assertE2eOnlyInE2eMode(mode: string, env?: Record<string, string | undefined>): void;
+/**
+ * The Vite configuration every MeddleWare tool app shares: the browserslist build target, the colour mode and season before first paint
+ * ({@link themeInit}), the e2e-build guard ({@link assertE2eOnlyInE2eMode}), and `@meddleware/wallet-adapter` excluded from dependency
+ * pre-bundling. The wallet adapter ships TS and `.vue` source and holds the shared wallet singleton; pre-bundling would put its TS in
+ * `.vite/deps` while its `.vue` files (which esbuild cannot bundle) are served raw and import the raw module, so dev would run two
+ * singletons and the guard and the app would see different connection state.
+ *
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * export default meddlewareApp({ plugins: [vue()] })
+ * ```
+ *
+ * @param {object} options
+ * @param {import('vite').PluginOption[]} options.plugins The app's plugins (`vue()` …); `themeInit` is added after them.
+ * @param {'light' | 'dark' | 'system'} [options.theme] The mode a first visit gets (default `dark`, the brand default).
+ * @param {boolean} [options.wallet] The app uses `@meddleware/wallet-adapter` (default true): keep it out of pre-bundling.
+ * @param {import('vite').UserConfig} [options.config] Anything else (`base`, `build.rollupOptions`, `server` …); `build` is merged.
+ * @returns {import('vite').UserConfigFnObject}
+ */
+export function meddlewareApp({ plugins, theme, wallet, config }: {
+    plugins: import("vite").PluginOption[];
+    theme?: "light" | "dark" | "system" | undefined;
+    wallet?: boolean | undefined;
+    config?: import("vite").UserConfig | undefined;
+}): import("vite").UserConfigFnObject;

package/dist/vitest.d.ts

@@ -4,6 +4,26 @@
  * renders a dialog; the browser's real behaviour (top layer, inert background) is checked by the Playwright suites, not jsdom.
  */
 export function installDialogShim(): void;
+/**
+ * The Vitest configuration of a MeddleWare Vue repository: jsdom, `tests/**\/*.test.ts`, a single copy of Vue for the code under test and
+ * `@vue/test-utils`, and the UI packages processed through Vite ({@link inlineMeddleware}).
+ *
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * export default defineConfig(vueTestConfig({ plugins: [vue()] }))
+ * ```
+ *
+ * @param {object} options
+ * @param {import('vite').PluginOption[]} options.plugins The Vue plugin (and any other the tests need).
+ * @param {import('vitest/config').TestUserConfig} [options.test] Overrides merged into `test` (`include`, `setupFiles`, `environment` …).
+ * @returns {import('vitest/config').ViteUserConfig & { test: import('vitest/config').TestUserConfig }}
+ */
+export function vueTestConfig({ plugins, test }: {
+    plugins: import("vite").PluginOption[];
+    test?: import("vitest/node").TestUserConfig | undefined;
+}): import("vitest/config").ViteUserConfig & {
+    test: import("vitest/config").TestUserConfig;
+};
 /**
  * Packages to process through Vite in tests: the ones that import CSS or `.vue` files. Vitest matches these against the module's resolved
  * file path (`…/node_modules/@meddleware/ui/dist/…`), not the package name, so the patterns match the path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meddleware/frontend-config",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "description": "Shared frontend tooling for MeddleWare apps: browser support, ESLint, Stylelint, html-validate, PostCSS, Playwright, axe, screenshots, Lighthouse and the Vite target.",
   "license": "0BSD",
@@ -23,7 +23,9 @@
     "src",
     "dist",
     "CHANGELOG.md",
-    "SECURITY.md"
+    "SECURITY.md",
+    "templates",
+    "tsconfig"
   ],
   "exports": {
     ".": {
@@ -86,7 +88,12 @@
     "./bundle": {
       "types": "./dist/bundle.d.ts",
       "default": "./src/bundle.js"
-    }
+    },
+    "./csp": {
+      "types": "./dist/csp.d.ts",
+      "default": "./src/csp.js"
+    },
+    "./tsconfig/vue-app.json": "./tsconfig/vue-app.json"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
@@ -164,6 +171,11 @@
     "not dead"
   ],
   "bin": {
-    "check-prod-bundle": "./src/check-prod-bundle.js"
+    "check-prod-bundle": "./src/check-prod-bundle.js",
+    "mw-audit-gate": "./src/audit-gate.js",
+    "mw-third-party-licenses": "./src/third-party-licenses.js",
+    "mw-check-csp-inline": "./src/check-csp-inline.js",
+    "mw-sync": "./src/sync.js",
+    "mw-network-status": "./src/network-status.js"
   }
 }

package/src/audit-gate.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// mw-audit-gate — CI dependency gate: `npm audit` at high/critical, minus advisories listed in
+// .github/audit-allowlist.json. Each entry needs a reason and an expiry date, so an
+// accepted advisory is re-reviewed instead of being ignored forever.
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+
+const ALLOWLIST = '.github/audit-allowlist.json'
+const LEVELS = new Set(['high', 'critical'])
+const GHSA = /^GHSA(-[23456789cfghjmpqrvwx]{4}){3}$/
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+
+let failed = false
+/** @param {string} msg */
+const fail = (msg) => {
+  console.log(`::error::${msg}`)
+  failed = true
+}
+
+const entries = existsSync(ALLOWLIST) ? JSON.parse(readFileSync(ALLOWLIST, 'utf8')) : []
+if (!Array.isArray(entries)) throw new Error(`${ALLOWLIST} must be an array`)
+const today = new Date().toISOString().slice(0, 10)
+const allowed = new Map()
+for (const e of entries) {
+  if (!GHSA.test(e?.id) || typeof e.reason !== 'string' || !e.reason || !DATE.test(e.expires)) {
+    fail(`invalid allowlist entry ${JSON.stringify(e)} (needs id, reason, expires YYYY-MM-DD)`)
+  } else if (e.expires < today) {
+    fail(`allowlist entry ${e.id} expired on ${e.expires}; re-review it`)
+  } else {
+    allowed.set(e.id, e)
+  }
+}
+
+let raw
+try {
+  raw = execFileSync('npm', ['audit', '--json'], { encoding: 'utf8', maxBuffer: 64 << 20 })
+} catch (err) {
+  // npm audit exits non-zero whenever it reports anything; the JSON is still on stdout.
+  raw = /** @type {{ stdout: string }} */ (err).stdout
+}
+const report = JSON.parse(raw)
+if (report.error) throw new Error(`npm audit failed: ${JSON.stringify(report.error)}`)
+
+const found = new Map()
+for (const vuln of Object.values(report.vulnerabilities ?? {})) {
+  for (const via of vuln.via) {
+    if (typeof via === 'object' && LEVELS.has(via.severity)) {
+      found.set(via.url.split('/').pop(), via)
+    }
+  }
+}
+
+for (const [id, via] of found) {
+  const entry = allowed.get(id)
+  if (entry) {
+    console.log(`::warning::${id} (${via.name}, ${via.severity}) allowed until ${entry.expires}: ${entry.reason}`)
+  } else {
+    fail(`${id} (${via.name}, ${via.severity}): ${via.title}`)
+  }
+}
+for (const id of allowed.keys()) {
+  if (!found.has(id)) console.log(`::warning::allowlist entry ${id} no longer matches an advisory; remove it`)
+}
+
+const open = [...found.keys()].filter((id) => !allowed.has(id)).length
+console.log(`${found.size} high/critical advisories, ${open} not allowlisted`)
+process.exit(failed ? 1 : 0)

package/src/check-csp-inline.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Fails the build when dist/ contains an inline <script> that the CSP's script-src does not allow, or when script-src allows
+// 'unsafe-inline'. VitePress inlines a couple of small scripts (the appearance/theme bootstrap and the page-hash map); the image serves a
+// hash-based CSP, so a VitePress upgrade (or a change of the `appearance` option) that changes them must update the Dockerfile's CSP ARG
+// in the same change — this check makes that impossible to miss, in CI as well as in the image build.
+//
+// Usage: mw-check-csp-inline "<csp>" [distDir]
+//        mw-check-csp-inline @Dockerfile [distDir]   (reads the Dockerfile's `ARG CSP="…"` default)
+import { createHash } from 'node:crypto'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const [source, dist = 'dist'] = process.argv.slice(2)
+if (!source) {
+  console.error('usage: mw-check-csp-inline "<csp>"|@Dockerfile [distDir]')
+  process.exit(2)
+}
+
+let csp = source
+if (source.startsWith('@')) {
+  const m = readFileSync(source.slice(1), 'utf8').match(/^ARG CSP="([^"]*)"/m)
+  if (!m?.[1]) {
+    console.error(`CSP check: no 'ARG CSP="…"' default found in ${source.slice(1)}`)
+    process.exit(2)
+  }
+  csp = m[1]
+}
+
+const scriptSrc = (csp.split(';').map((d) => d.trim()).find((d) => d.startsWith('script-src ')) ?? '').split(/\s+/)
+if (scriptSrc.includes("'unsafe-inline'")) {
+  console.error("CSP check: script-src allows 'unsafe-inline'; the page must not.")
+  process.exit(1)
+}
+const allowed = new Set(scriptSrc.filter((t) => t.startsWith("'sha256-")).map((t) => t.slice(1, -1)))
+
+/**
+ * @param {string} dir
+ * @returns {Generator<string>}
+ */
+function* htmlFiles(dir) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name)
+    if (statSync(p).isDirectory()) yield* htmlFiles(p)
+    else if (name.endsWith('.html')) yield p
+  }
+}
+
+const missing = new Map()
+let files = 0
+for (const file of htmlFiles(dist)) {
+  files++
+  const html = readFileSync(file, 'utf8')
+  for (const m of html.matchAll(/<script(?![^>]*\bsrc=)[^>]*>([\s\S]*?)<\/script>/g)) {
+    if (!m[1].trim()) continue
+    const hash = 'sha256-' + createHash('sha256').update(m[1]).digest('base64')
+    if (!allowed.has(hash)) missing.set(hash, file)
+  }
+}
+if (files === 0) {
+  console.error(`CSP check: no HTML file found in ${dist}; build first.`)
+  process.exit(2)
+}
+if (missing.size) {
+  console.error(`CSP check: ${missing.size} inline script(s) not allowed by script-src:`)
+  for (const [hash, file] of missing) console.error(`  '${hash}'  (first seen in ${file})`)
+  process.exit(1)
+}
+console.log(`CSP check: every inline script in ${files} HTML file(s) is allowed by script-src.`)

package/src/csp.js

@@ -0,0 +1,67 @@
+// @ts-check
+// The Content-Security-Policy of a MeddleWare static site, built from a named profile. Every frontend image serves one (the Dockerfile's `ARG CSP`,
+// handed to static-server): twelve hand-copied strings drifted in small ways, so the profiles live here and `mw-sync` checks each Dockerfile against its
+// profile. A policy has no 'unsafe-inline' for scripts (`mw-check-csp-inline` fails the build on an inline script that is not allowed by hash).
+
+/**
+ * @typedef {object} CspOptions
+ * @property {boolean} [wasm] allow WebAssembly (`'wasm-unsafe-eval'`): the Walrus and Move-bytecode clients
+ * @property {boolean} [chain] chain-facing app: https images, https connections (RPC, relay, aggregator and key-server hosts are partly configured), blob workers
+ * @property {boolean} [worker] allow `worker-src 'self' blob:` without the rest of `chain` (VitePress sites)
+ * @property {boolean} [strict] `base-uri` and `form-action` are `'none'` (a page with no forms and no `<base>`)
+ * @property {'self' | 'none'} [frameAncestors] who may frame the page (default `'self'`)
+ * @property {string[]} [scriptHashes] `'sha256-…'` sources for the inline scripts a static-site generator emits
+ */
+
+/** @type {Record<string, CspOptions>} */
+export const PROFILES = {
+  /** Same-origin only: the landing page. */
+  static: {},
+  /** Same-origin only, no forms and no `<base>`: the status page and the public roadmap. */
+  'static-strict': { strict: true },
+  /** An operator console: same-origin only and never framed. */
+  console: { frameAncestors: 'none' },
+  /** A chain-facing tool: https connections and images, blob workers. */
+  chain: { chain: true },
+  /** A chain-facing tool that runs WebAssembly (Walrus, Move bytecode). */
+  'chain-wasm': { chain: true, wasm: true },
+  /** A VitePress site: same-origin connections, https images, blob workers, inline scripts allowed by hash (the hashes are kept from the current policy). */
+  docs: { worker: true },
+}
+
+/**
+ * @param {CspOptions} options
+ * @returns {string}
+ */
+export function buildCsp(options = {}) {
+  const { wasm = false, chain = false, worker = false, strict = false, frameAncestors = 'self', scriptHashes = [] } = options
+  const script = ["'self'", ...(wasm ? ["'wasm-unsafe-eval'"] : []), ...scriptHashes.map((h) => `'${h.replace(/^'|'$/g, '')}'`)]
+  const richImages = chain || worker
+  const directives = [
+    ["default-src", "'self'"],
+    ['script-src', script.join(' ')],
+    ['style-src', "'self' 'unsafe-inline'"],
+    ['img-src', richImages ? "'self' data: blob: https:" : "'self' data:"],
+    ['font-src', "'self' data:"],
+    ['connect-src', chain ? "'self' https:" : "'self'"],
+    ...(chain || worker ? [['worker-src', "'self' blob:"]] : []),
+    ['object-src', "'none'"],
+    ['base-uri', strict ? "'none'" : "'self'"],
+    ['form-action', strict ? "'none'" : "'self'"],
+    ['frame-ancestors', `'${frameAncestors}'`],
+  ]
+  return [...directives.map(([d, v]) => `${d} ${v}`), 'upgrade-insecure-requests'].join('; ')
+}
+
+/** The `'sha256-…'` hashes in a policy's script-src (kept when a profile such as `docs` is rebuilt). */
+export function scriptHashesOf(/** @type {string} */ csp) {
+  const src = csp.split(';').map((d) => d.trim()).find((d) => d.startsWith('script-src ')) ?? ''
+  return src.split(/\s+/).filter((t) => t.startsWith("'sha256-")).map((t) => t.slice(1, -1))
+}
+
+/** @param {string} name @param {string} [current] the policy now in the Dockerfile (its script hashes are kept) */
+export function cspForProfile(name, current = '') {
+  const profile = PROFILES[name]
+  if (!profile) throw new Error(`unknown CSP profile "${name}" (known: ${Object.keys(PROFILES).join(', ')})`)
+  return buildCsp({ ...profile, ...(name === 'docs' ? { scriptHashes: scriptHashesOf(current) } : {}) })
+}

package/src/network-status.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// @ts-check
+// mw-network-status — write which networks MeddleWare is deployed on, from the deployment records of the installed client packages, so a static
+// site (landing page, docs, developer docs) says "mainnet is coming" until the records have a `mainnet` key and says "live" the moment they do.
+//
+//   mw-network-status [--out src/network.json]     (default: print to stdout)
+//
+// Run it from the repository root before the build (a `prebuild` script). The repository needs `@meddleware/web-utils` and the two clients
+// (`@meddleware/access-gate-client`, `@meddleware/sealed-storage-client`) installed; it fails when one is missing rather than guess.
+import { writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** @param {string} name */
+async function load(name) {
+  const require = createRequire(join(process.cwd(), 'noop.js'))
+  return import(pathToFileURL(require.resolve(name)).href)
+}
+
+/**
+ * @param {{ networkAvailability: Function }} utils
+ * @param {Record<string, Record<string, unknown>>} records product name → its deployments object
+ */
+export function networkStatus(utils, records) {
+  return utils.networkAvailability(Object.fromEntries(Object.entries(records).map(([name, deployments]) => [name, Object.keys(deployments)])))
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const args = process.argv.slice(2)
+  const outIndex = args.indexOf('--out')
+  const out = outIndex >= 0 ? args[outIndex + 1] : undefined
+  try {
+    const utils = await load('@meddleware/web-utils')
+    const gate = await load('@meddleware/access-gate-client')
+    const sealed = await load('@meddleware/sealed-storage-client')
+    const status = networkStatus(utils, { 'access gate': gate.ACCESS_GATE_DEPLOYMENTS, 'sealed storage': sealed.SEAL_POLICIES_DEPLOYMENTS })
+    const json = JSON.stringify(status, null, 2) + '\n'
+    if (out) writeFileSync(out, json)
+    else process.stdout.write(json)
+  } catch (err) {
+    console.error(`mw-network-status: ${err instanceof Error ? err.message : String(err)}`)
+    process.exit(1)
+  }
+}

package/src/sync.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// @ts-check
+// mw-sync — keep the files that every MeddleWare frontend repository copies from this package identical to the package's templates, and the
+// Dockerfile's Content-Security-Policy equal to its named profile. Run in a repository root:
+//
+//   mw-sync --check    fail (exit 1) when a file differs; print which and how to fix
+//   mw-sync --write    overwrite the files with the templates / the profile's policy
+//
+// The repository declares what it is in package.json:
+//   "meddleware": { "kind": "app", "csp": "chain-wasm", "lhci": true }
+//   kind  "app"  → .github/dependabot.yml, .dockerignore, postcss.config.js, stylelint.config.js are the templates
+//   csp   a profile of ./csp.js → the Dockerfile's `ARG CSP="…"` is that profile's policy (`docs` keeps the script hashes already there)
+//   lhci  true   → .github/audit-allowlist.json is the template (the dated allowlist for the Lighthouse CI tool chain; one expiry, reviewed together)
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { cspForProfile } from './csp.js'
+
+const templates = join(dirname(fileURLToPath(import.meta.url)), '..', 'templates')
+const tpl = (/** @type {string} */ name) => readFileSync(join(templates, name), 'utf8')
+
+/**
+ * @param {string} root repository root
+ * @param {{ write?: boolean }} [options]
+ * @returns {{ file: string, ok: boolean, note: string }[]}
+ */
+export function sync(root, options = {}) {
+  const pkgPath = join(root, 'package.json')
+  const pkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, 'utf8')) : {}
+  const cfg = pkg.meddleware ?? {}
+  /** @type {{ file: string, ok: boolean, note: string }[]} */
+  const out = []
+  /** @param {string} file @param {string} want */
+  const expectFile = (file, want) => {
+    const p = join(root, file)
+    const have = existsSync(p) ? readFileSync(p, 'utf8') : null
+    if (have === want) return out.push({ file, ok: true, note: 'matches the template' })
+    if (options.write) {
+      mkdirSync(dirname(p), { recursive: true })
+      writeFileSync(p, want)
+      return out.push({ file, ok: true, note: have === null ? 'created' : 'rewritten' })
+    }
+    out.push({ file, ok: false, note: have === null ? 'missing (mw-sync --write creates it)' : 'differs from the template (mw-sync --write restores it)' })
+  }
+  if (cfg.kind === 'app') {
+    expectFile('.github/dependabot.yml', tpl('dependabot.app.yml'))
+    expectFile('.dockerignore', tpl('dockerignore'))
+    expectFile('postcss.config.js', tpl('postcss.config.js'))
+    expectFile('stylelint.config.js', tpl('stylelint.config.js'))
+  }
+  if (cfg.lhci === true) expectFile('.github/audit-allowlist.json', tpl('audit-allowlist.lhci.json'))
+  if (cfg.csp) {
+    const df = join(root, 'Dockerfile')
+    const text = existsSync(df) ? readFileSync(df, 'utf8') : ''
+    const m = text.match(/^ARG CSP="([^"]*)"/m)
+    if (!m) out.push({ file: 'Dockerfile', ok: false, note: `no 'ARG CSP="…"' default found (profile ${cfg.csp})` })
+    else {
+      const want = cspForProfile(cfg.csp, m[1])
+      if (m[1] === want) out.push({ file: 'Dockerfile', ok: true, note: `CSP equals the "${cfg.csp}" profile` })
+      else if (options.write) {
+        writeFileSync(df, text.replace(/^ARG CSP="[^"]*"/m, () => `ARG CSP="${want}"`))
+        out.push({ file: 'Dockerfile', ok: true, note: `CSP rewritten to the "${cfg.csp}" profile` })
+      } else out.push({ file: 'Dockerfile', ok: false, note: `CSP differs from the "${cfg.csp}" profile:\n    have ${m[1]}\n    want ${want}` })
+    }
+  }
+  if (out.length === 0) out.push({ file: 'package.json', ok: false, note: 'no "meddleware" section: nothing to check (add kind / csp / lhci)' })
+  return out
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const args = process.argv.slice(2)
+  const write = args.includes('--write')
+  if (!write && !args.includes('--check')) {
+    console.error('usage: mw-sync --check | --write')
+    process.exit(2)
+  }
+  const results = sync(process.cwd(), { write })
+  for (const r of results) console.log(`${r.ok ? 'ok  ' : 'FAIL'} ${r.file}: ${r.note}`)
+  process.exit(results.every((r) => r.ok) ? 0 : 1)
+}

package/src/third-party-licenses.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Writes dist/THIRD_PARTY_LICENSES: the licence and NOTICE texts of every production dependency in
+// package-lock.json. The site ships a bundle, so the packages' own files do not travel with it;
+// Apache-2.0 (§4), MIT and BSD all require the notice to accompany a redistribution. The file is served
+// with the site (/THIRD_PARTY_LICENSES) and read by licence audits.
+//
+//   mw-third-party-licenses            write the file
+//   mw-third-party-licenses --check    also fail when the file would be empty
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+// The project root is the directory the command runs in (an app's npm script), not this package.
+const root = process.cwd()
+const lock = JSON.parse(readFileSync(join(root, 'package-lock.json'), 'utf8'))
+const check = process.argv.includes('--check')
+const LICENSE_FILE = /^(licen[cs]e|notice|copying|unlicense)(\.|$|-)/i
+
+const out = []
+const missing = []
+const apacheMissing = []
+/** @param {any} pkg */
+const declared = (pkg) => (typeof pkg.license === 'string' ? pkg.license : JSON.stringify(pkg.license ?? pkg.licenses ?? 'unknown'))
+/** @param {any} pkg */
+const holder = (pkg) =>
+  [pkg.author && (typeof pkg.author === 'string' ? pkg.author : pkg.author.name), pkg.repository && (typeof pkg.repository === 'string' ? pkg.repository : pkg.repository.url)]
+    .filter(Boolean)
+    .join(' · ')
+const names = Object.keys(lock.packages)
+  .filter((p) => p.startsWith('node_modules/') && !lock.packages[p].dev && !lock.packages[p].optional)
+  .sort()
+for (const p of names) {
+  const dir = join(root, p)
+  if (!existsSync(dir)) continue
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+  const files = readdirSync(dir).filter((f) => LICENSE_FILE.test(f)).sort()
+  out.push(`${'='.repeat(78)}\n${pkg.name}@${pkg.version}  (${declared(pkg)})\n${'='.repeat(78)}`)
+  if (files.length === 0) {
+    missing.push(`${pkg.name}@${pkg.version}`)
+    if (/Apache-2\.0/.test(declared(pkg))) apacheMissing.push(`${pkg.name}@${pkg.version}`)
+  }
+  for (const f of files) out.push(`--- ${f} ---\n${readFileSync(join(dir, f), 'utf8').trim()}\n`)
+  if (files.length === 0) {
+    const apache = /Apache-2\.0/.test(declared(pkg))
+    out.push(`(the package ships no licence file; declared licence: ${declared(pkg)}${holder(pkg) ? `; ${holder(pkg)}` : ''}${apache ? '; the Apache License 2.0 text follows at the end of this file' : ''})\n`)
+  }
+}
+// Apache-2.0 §4(a) asks that a recipient gets a copy of the License. A package that declares it but ships no
+// file is covered by the canonical text, taken from any installed package that carries it.
+if (apacheMissing.length > 0) {
+  let text = null
+  for (const p of Object.keys(lock.packages).filter((k) => k.startsWith('node_modules/'))) {
+    const dir = join(root, p)
+    if (!existsSync(dir)) continue
+    for (const f of readdirSync(dir).filter((x) => LICENSE_FILE.test(x))) {
+      const t = readFileSync(join(dir, f), 'utf8')
+      if (/Apache License\s+Version 2\.0, January 2004/.test(t) && /END OF TERMS AND CONDITIONS/.test(t)) {
+        text = t.slice(0, t.indexOf('END OF TERMS AND CONDITIONS') + 'END OF TERMS AND CONDITIONS'.length).trim()
+        break
+      }
+    }
+    if (text) break
+  }
+  out.push(`${'='.repeat(78)}\nApache License 2.0 — applies to: ${apacheMissing.join(', ')}\n${'='.repeat(78)}`)
+  out.push(text ?? '(canonical text not found in the installed packages: see https://www.apache.org/licenses/LICENSE-2.0)')
+  if (check && text === null) {
+    console.error('Apache-2.0 packages without a licence file, and no canonical Apache License text installed')
+    process.exit(1)
+  }
+}
+mkdirSync(join(root, 'dist'), { recursive: true })
+writeFileSync(join(root, 'dist', 'THIRD_PARTY_LICENSES'), `${out.join('\n')}\n`)
+console.log(`THIRD_PARTY_LICENSES: ${names.length} production packages, ${missing.length} without a licence file`)
+if (missing.length) console.log(`  no licence file: ${missing.join(', ')}`)
+if (check && out.length === 0) {
+  console.error('no production packages found in package-lock.json')
+  process.exit(1)
+}

package/src/vite.js

@@ -85,3 +85,34 @@ export function assertE2eOnlyInE2eMode(mode, env = process.env) {
     throw new Error(`VITE_E2E is set but the build mode is "${mode}": the end-to-end build is \`vite build --mode e2e\`, and nothing else may include the test wallet.`)
   }
 }
+
+/**
+ * The Vite configuration every MeddleWare tool app shares: the browserslist build target, the colour mode and season before first paint
+ * ({@link themeInit}), the e2e-build guard ({@link assertE2eOnlyInE2eMode}), and `@meddleware/wallet-adapter` excluded from dependency
+ * pre-bundling. The wallet adapter ships TS and `.vue` source and holds the shared wallet singleton; pre-bundling would put its TS in
+ * `.vite/deps` while its `.vue` files (which esbuild cannot bundle) are served raw and import the raw module, so dev would run two
+ * singletons and the guard and the app would see different connection state.
+ *
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * export default meddlewareApp({ plugins: [vue()] })
+ * ```
+ *
+ * @param {object} options
+ * @param {import('vite').PluginOption[]} options.plugins The app's plugins (`vue()` …); `themeInit` is added after them.
+ * @param {'light' | 'dark' | 'system'} [options.theme] The mode a first visit gets (default `dark`, the brand default).
+ * @param {boolean} [options.wallet] The app uses `@meddleware/wallet-adapter` (default true): keep it out of pre-bundling.
+ * @param {import('vite').UserConfig} [options.config] Anything else (`base`, `build.rollupOptions`, `server` …); `build` is merged.
+ * @returns {import('vite').UserConfigFnObject}
+ */
+export function meddlewareApp({ plugins, theme = 'dark', wallet = true, config = {} }) {
+  return ({ mode }) => {
+    assertE2eOnlyInE2eMode(mode)
+    return {
+      ...config,
+      build: { target: viteTarget(), ...config.build },
+      plugins: [...plugins, themeInit({ default: theme })],
+      ...(wallet ? { optimizeDeps: { ...config.optimizeDeps, exclude: ['@meddleware/wallet-adapter', ...(config.optimizeDeps?.exclude ?? [])] } } : {}),
+    }
+  }
+}

package/src/vitest.js

@@ -50,3 +50,32 @@ export function installDialogShim() {
     this.dispatchEvent(new Event('close'))
   }
 }
+
+/**
+ * The Vitest configuration of a MeddleWare Vue repository: jsdom, `tests/**\/*.test.ts`, a single copy of Vue for the code under test and
+ * `@vue/test-utils`, and the UI packages processed through Vite ({@link inlineMeddleware}).
+ *
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * export default defineConfig(vueTestConfig({ plugins: [vue()] }))
+ * ```
+ *
+ * @param {object} options
+ * @param {import('vite').PluginOption[]} options.plugins The Vue plugin (and any other the tests need).
+ * @param {import('vitest/config').TestUserConfig} [options.test] Overrides merged into `test` (`include`, `setupFiles`, `environment` …).
+ * @returns {import('vitest/config').ViteUserConfig & { test: import('vitest/config').TestUserConfig }}
+ */
+export function vueTestConfig({ plugins, test = {} }) {
+  const inline = test.server?.deps?.inline
+  return {
+    plugins,
+    resolve: { dedupe: ['vue', '@vue/test-utils'] },
+    test: {
+      environment: 'jsdom',
+      include: ['tests/**/*.test.ts'],
+      exclude: ['node_modules/**'],
+      ...test,
+      server: { ...test.server, deps: { ...test.server?.deps, inline: inline === true ? true : [...inlineMeddleware, ...(inline ?? [])] } },
+    },
+  }
+}

package/templates/audit-allowlist.lhci.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": "GHSA-jmr9-qjv8-65gv",
+    "reason": "extract-zip has no patched release. It is a dev-only transitive of @lhci/cli (lighthouse > puppeteer-core > @puppeteer/browsers) and only unpacks browser archives that Lighthouse CI downloads itself; nothing from it ships in the image.",
+    "expires": "2027-01-31"
+  },
+  {
+    "id": "GHSA-7pqw-9j4j-h8q3",
+    "reason": "extract-zip has no patched release. It is a dev-only transitive of @lhci/cli (lighthouse > puppeteer-core > @puppeteer/browsers) and only unpacks browser archives that Lighthouse CI downloads itself; nothing from it ships in the image.",
+    "expires": "2027-01-31"
+  }
+]

package/templates/dependabot.app.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    ignore:
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
+    groups:
+      npm-minor-patch:
+        update-types: [minor, patch]
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    ignore:
+      - dependency-name: "golang"
+        update-types: ["version-update:semver-minor", "version-update:semver-major"]
+    groups:
+      docker:
+        patterns: ['*']
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns: ['*']

package/templates/dockerignore

@@ -0,0 +1,13 @@
+# Build context: sources only. The image runs its own `npm ci` and production build, so local
+# installs and build output never enter it — and local-only env files (Vite loads `.env*.local` in
+# every mode) can never be baked into the production bundle. Committed `.env` / `.env.production`
+# defaults stay in the context on purpose.
+node_modules
+dist
+.git
+.github
+.env*.local
+*.log
+test-results
+playwright-report
+coverage

package/templates/postcss.config.js

@@ -0,0 +1 @@
+export { default } from '@meddleware/frontend-config/postcss'

package/templates/stylelint.config.js

@@ -0,0 +1,3 @@
+import { stylelintConfig } from '@meddleware/frontend-config/stylelint'
+
+export default stylelintConfig()

package/tsconfig/vue-app.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "jsx": "preserve",
+    "types": ["node"],
+    "noEmit": true
+  }
+}