@rexezuge/tooling 0.0.0-stage → 1.0.0

package/src/test/integration-migrations.ts

@@ -0,0 +1,267 @@
+/**
+ * Applying the migration directory to a D1 binding — as a factory.
+ *
+ * Provenance: converged from `test/integration/helpers/migrations.ts` in six repos
+ * (AWS-AccessBridge, ChordDHT-Tracker, Durable-DAV, Durable-DAV-Router, Edge-Git,
+ * Mail-Meow) and `test/helpers/migrations.ts` in two more (CalDAV-Bridge,
+ * Edge-Sonic). All eight are the same file: a SQL splitter plus a range-addressed
+ * `applyMigrations`.
+ *
+ * ### Why it is a factory and not a module
+ *
+ * Every source file hardcodes where the migrations live, either as a
+ * `__INTEGRATION_MIGRATION_FILES__` binding injected by the Vitest config's
+ * `define`, or as a path derived from `import.meta.url`. The kit cannot know
+ * either, so the directory is an argument and the injection stays available as an
+ * option. One call to `createMigrationHelper({ migrationsDir })` gives the consumer
+ * the same helper their repo already has.
+ *
+ * ### What each source contributes
+ *
+ * - **Durable-DAV** — the trigger-aware splitter. `CREATE TRIGGER … BEGIN … END;`
+ *   bodies contain semicolons that must not split, and a naive splitter produces
+ *   statements SQLite rejects mid-migration. The BEGIN/END depth is tracked only
+ *   outside strings and comments, and the word *before* `TRIGGER` disambiguates
+ *   `CREATE TRIGGER` from a table called `trigger`. Durable-DAV also applies one
+ *   file per `batch()` and names the offending statement in the error, which is
+ *   the difference between "0007 failed" and a line number.
+ * - **AWS-AccessBridge** — the once-per-database guard. D1 records which
+ *   migrations have run; this helper does the same, because `ALTER TABLE … ADD
+ *   COLUMN` is not idempotent in SQLite and re-running the bundle fails with
+ *   "duplicate column name". A `WeakMap` keyed on the binding is the right scope
+ *   because each test file gets its own database. AWS also keeps `next` out of the
+ *   line-comment branch, which never reads it, and preserves newlines inside block
+ *   comments so an error's line numbers still point at the file.
+ * - **Edge-Sonic** — reading the directory off disk rather than a `define`
+ *   binding, because a test that names one hardcoded file cannot tell **a new
+ *   migration** from **an edit to an old one**, so it goes on passing through a
+ *   schema change that never reached production.
+ *
+ * ### The splitter is not here
+ *
+ * The statement splitter — with all of Durable-DAV's trigger-aware rules and its
+ * comment-level history — lives once, in `@rexezuge/d1`. `@rexezuge/identity`'s
+ * migration applier delegates to the same module, so the splitter cannot drift
+ * between the suite helper and the production applier. The re-exports below keep
+ * this file's public surface identical to the source repos'.
+ *
+ * ### The lock is asserted, not reimplemented
+ *
+ * D1 records applied migrations by *filename*, so an applied migration is immutable
+ * in fact while being an ordinary text file in appearance. That fact lives in
+ * `migrations/migrations.lock.json`, and the rules that check it live once, in
+ * `scripts/verify-migrations.ts` — the same module the CI gate runs. This helper
+ * deliberately does not parse the lock itself: a second implementation of a thing
+ * already written is free to disagree with the first, and the two disagreeing would
+ * leave a suite green against a lock CI rejects.
+ *
+ * ### Generic over the binding
+ *
+ * `D1DatabaseLike` is structural — `prepare`, and `batch` when the runtime has it
+ * — so a fake D1 in a unit test, a real D1 in the workerd integration suite, and
+ * Miniflare's D1 all satisfy it without an import of `@cloudflare/workers-types`.
+ * `batch` is used when present (Durable-DAV's shape: one round trip per file, and
+ * the failure names the file) and a sequential `prepare().run()` loop otherwise
+ * (AWS's shape: works on a binding with no batch support).
+ */
+
+import { executableStatements, splitSql } from '@rexezuge/d1';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * One migration file, as it is read.
+ */
+export interface MigrationFile {
+  /** Bare filename, e.g. `0007_replication.sql`. */
+  name: string;
+  /** The file's full text. */
+  sql: string;
+}
+
+/**
+ * The subset of a D1 prepared statement this helper uses.
+ */
+export interface D1PreparedStatementLike {
+  run(): Promise<unknown>;
+}
+
+/**
+ * The subset of a D1 binding this helper uses.
+ *
+ * `batch` is optional because not every binding that can prepare a statement can
+ * batch one; where it exists it is the better path, and where it does not the
+ * sequential loop is equivalent for a migration whose statements are independent.
+ */
+export interface D1DatabaseLike {
+  prepare(sql: string): D1PreparedStatementLike;
+  batch?(statements: readonly D1PreparedStatementLike[]): Promise<unknown>;
+}
+
+/**
+ * A closed range of migration files, by filename.
+ *
+ * Both ends inclusive, because "up to and including 0006" is the natural way to
+ * seed a pre-migration database and then apply the migration under test.
+ */
+export interface MigrationRange {
+  from?: string;
+  to?: string;
+}
+
+/**
+ * What `createMigrationHelper` accepts.
+ */
+export interface MigrationHelperOptions {
+  /**
+   * Directory holding the `.sql` files. Read top-level only, matching wrangler's
+   * default `${migrationsDir}/*.sql`, so the helper describes exactly the set
+   * wrangler will run.
+   */
+  readonly migrationsDir: string;
+  /**
+   * Migration files to use instead of reading `migrationsDir`.
+   *
+   * The escape hatch for a harness that embeds the SQL at build time. Same shape
+   * as the `__INTEGRATION_MIGRATION_FILES__` binding the source repos inject.
+   */
+  readonly files?: readonly MigrationFile[];
+}
+
+/**
+ * A bound migration helper.
+ */
+export interface MigrationHelper {
+  /** Every migration, in apply order. */
+  migrationFiles(): MigrationFile[];
+  /** The filenames, in apply order. */
+  migrationFileNames(): string[];
+  /** The concatenation of every file, in apply order — what a fresh database becomes. */
+  migrationSql(): string;
+  /** One file's SQL, by name. "What does *this* file say", not "what does the set say". */
+  migrationSqlOf(name: string): string;
+  /** Split one file into statements, comments included. */
+  splitSql(sql: string): string[];
+  /** The statements of one file that SQLite will actually execute. */
+  executableStatements(sql: string): string[];
+  /**
+   * Apply a range of migrations, at most once per database and range.
+   *
+   * Per file rather than one batch for everything, so a test can stop between
+   * files: the identity-upgrade test needs to seed the *pre-0004* shape and then
+   * apply 0004 to it.
+   */
+  applyMigrations(db: D1DatabaseLike, range?: MigrationRange): Promise<void>;
+}
+
+/**
+ * Reads every `.sql` file in `dir`, in apply order.
+ *
+ * Sort is the filename sort D1 itself uses, rather than a numeric parse of the
+ * prefix: wrangler hands the directory to SQLite in lexicographic order, so a
+ * suite that reads it numerically disagrees with production on any prefix wider
+ * than four digits.
+ */
+export function readMigrationFiles(dir: string): MigrationFile[] {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.sql'))
+    .map((entry) => ({ name: entry.name, sql: readFileSync(join(dir, entry.name), 'utf8') }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/**
+ * Strip leading `--` and block comments, which the splitter folds into the
+ * statement it then reports on.
+ */
+function stripLeadingComments(statement: string): string {
+  let out = statement;
+  for (;;) {
+    const next = out.replace(/^\s*(?:--[^\n]*\n|\/\*[\s\S]*?\*\/)\s*/, '');
+    if (next === out) return out.trim();
+    out = next;
+  }
+}
+
+/** Re-exported for surface parity with the source repos — the rules live in @rexezuge/d1. */
+export { executableStatements, splitSql };
+
+/**
+ * Bind a migration directory into a helper.
+ *
+ * ```ts
+ * const migrations = createMigrationHelper({ migrationsDir: path.join(REPO_ROOT, 'migrations') });
+ * await migrations.applyMigrations(env.DB);
+ * ```
+ */
+export function createMigrationHelper(options: MigrationHelperOptions): MigrationHelper {
+  const files = options.files !== undefined ? [...options.files] : readMigrationFiles(options.migrationsDir);
+
+  /**
+   * Databases this helper has already migrated, keyed by the range applied.
+   *
+   * A `WeakMap` rather than a module-level `Set`, because the guard is per
+   * binding: two databases in one suite each need the bundle applied once, and a
+   * module-level set would silently skip the second.
+   */
+  const applied = new WeakMap<D1DatabaseLike, string>();
+
+  const indexOf = (name: string | undefined, fallback: number): number => {
+    if (name === undefined) return fallback;
+    const found = files.findIndex((file) => file.name === name);
+    if (found === -1) {
+      throw new Error(`Unknown migration file: ${name}. Available: ${files.map((file) => file.name).join(', ')}`);
+    }
+    return found;
+  };
+
+  return {
+    migrationFiles: () => files.map((file) => ({ ...file })),
+    migrationFileNames: () => files.map((file) => file.name),
+    migrationSql: () => files.map((file) => file.sql).join('\n'),
+    migrationSqlOf: (name: string) => {
+      const file = files.find((candidate) => candidate.name === name);
+      if (file === undefined) {
+        throw new Error(`Unknown migration file: ${name}. Available: ${files.map((candidate) => candidate.name).join(', ')}`);
+      }
+      return file.sql;
+    },
+    splitSql,
+    executableStatements,
+    applyMigrations: async (db: D1DatabaseLike, range?: MigrationRange): Promise<void> => {
+      const start = indexOf(range?.from, 0);
+      const end = indexOf(range?.to, files.length - 1);
+      const key = `${start}:${end}`;
+      if (applied.get(db) === key) return;
+      const applicable = files.slice(start, end + 1);
+
+      for (const file of applicable) {
+        const statements = executableStatements(file.sql);
+        if (statements.length === 0) continue;
+
+        if (typeof db.batch === 'function') {
+          try {
+            await db.batch(statements.map((sql) => db.prepare(sql)));
+          } catch (error: unknown) {
+            // A batch reports only the file's single failure, so name the statement:
+            // a migration error that says nothing about which of its nine statements
+            // broke is a migration error nobody fixes.
+            throw new Error(
+              `${file.name}: batch of ${statements.length} statements failed at ${stripLeadingComments(statements.at(-1) ?? '').slice(0, 200)}: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+              { cause: error },
+            );
+          }
+          continue;
+        }
+
+        for (const sql of statements) {
+          await db.prepare(sql).run();
+        }
+      }
+
+      applied.set(db, key);
+    },
+  };
+}

package/src/test/mocks/cloudflare-workers.ts

@@ -0,0 +1,115 @@
+/**
+ * Stand-in for the `cloudflare:workers` module, which has no Node equivalent.
+ *
+ * Provenance: converged from the eight copies at `test/mocks/cloudflare-workers.ts`
+ * (AWS-AccessBridge, CalDAV-Bridge, ChordDHT-Tracker, Durable-DAV, Edge-Git,
+ * Edge-Sonic, Mail-Meow, Mail-Otter). All eight are the same twenty lines; the
+ * union is three base classes and the union exists because each repo discovered a
+ * missing one the hard way.
+ *
+ * ### What each source contributes
+ *
+ * - **DurableObject** — every copy. Stores `ctx` and `env` so a real DO class can
+ *   be constructed and its lifecycle RPCs driven directly, without Miniflare.
+ * - **`RpcTarget`** — Durable-DAV's, and the reason is load-bearing rather than
+ *   tidy: `dofs`' `Fs` class `extends RpcTarget`, so the module fails to evaluate
+ *   with *"Class extends value undefined"* when the base is missing. That is a
+ *   module-load error, not a test failure, so it surfaces as an unimportable
+ *   `dav-store` barrel and no unit test can reach `DavRepository`. Deliberately
+ *   empty: on the platform it marks which methods are callable across an RPC
+ *   boundary, and nothing in a Node suite calls those through RPC. An empty base
+ *   keeps the fake honest instead of pretending to implement dispatch.
+ * - **`WorkflowEntrypoint`** — Edge-Git, Edge-Sonic, Mail-Meow, Mail-Otter. A
+ *   Workflow class extends it, so the mock must provide it or the module fails the
+ *   same way — a **startup** error, which therefore takes down every suite that
+ *   reaches `apps/background` for an unrelated reason. Edge-Sonic's is the shape
+ *   kept: it stores `ctx` as well as `env`, because the failure policy under test
+ *   in `runWorkflow` lives in a plain function precisely so it can be exercised
+ *   without workerd, and that policy reads the execution context.
+ *
+ * ### Why the ambient types are declared here rather than imported
+ *
+ * The source repos name `DurableObjectState`, `ExecutionContext` and `Env`
+ * unqualified, which resolves only because `worker-configuration.d.ts` and
+ * `@cloudflare/workers-types` are ambient inside a Wrangler project. This copy is
+ * imported by the kit's own typecheck, where neither exists, so the two state
+ * shapes are declared locally and `TEnv` defaults to `unknown` instead of `Env`
+ * (Edge-Sonic's form). A local declaration shadows the ambient one inside this
+ * file only, so a consumer's copy typechecks against their generated types
+ * exactly as the original did.
+ *
+ * ### Usage in a consumer
+ *
+ * Copy this file to `<repo>/test/mocks/cloudflare-workers.ts` and alias the
+ * specifier in the Vitest config — `defineUnitVitestConfig()` already does:
+ *
+ * ```jsonc
+ * // wrangler.jsonc / vitest alias
+ * "cloudflare:workers": "test/mocks/cloudflare-workers.ts"
+ * ```
+ *
+ * Only what a test actually imports is exported. A symbol here that nothing
+ * imports is not a safety net; it is a claim that something depends on it.
+ */
+
+/**
+ * The subset of `DurableObjectState` a Node test reaches.
+ *
+ * Declared structurally rather than imported: `id`, `storage` and `waitUntil` are
+ * the three a hand-driven lifecycle touches, and nothing here needs the rest.
+ */
+export interface DurableObjectState {
+  readonly id: { toString(): string; readonly name?: string };
+}
+
+/**
+ * The subset of `ExecutionContext` a Node test reaches.
+ *
+ * `waitUntil` is present because a Workflow's `run()` is driven through it, and
+ * `passThroughOnException` is absent on purpose — nothing in a Node suite wires a
+ * request through it.
+ */
+export interface ExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/**
+ * The base class every Durable Object extends.
+ *
+ * `protected`, exactly as on the platform: a DO subclass reads `this.env` and
+ * `this.ctx`, and nothing outside it may.
+ */
+class DurableObject<TEnv = unknown> {
+  protected ctx: DurableObjectState;
+  protected env: TEnv;
+
+  constructor(ctx: DurableObjectState, env: TEnv) {
+    this.ctx = ctx;
+    this.env = env;
+  }
+}
+
+/**
+ * The base class `dofs`' `Fs` extends. See the header: an empty body is the
+ * whole point, and a missing class is a module-load failure.
+ */
+class RpcTarget {}
+
+/**
+ * The base class every Workflow extends.
+ *
+ * `ctx` is `ExecutionContext` rather than `unknown` (Mail-Meow/Mail-Otter's
+ * form) because a Workflow's step code reads it; `void ctx` to silence the unused
+ * warning would be a lie about which of the two a subclass uses.
+ */
+class WorkflowEntrypoint<TEnv = unknown> {
+  protected ctx: ExecutionContext;
+  protected env: TEnv;
+
+  constructor(ctx: ExecutionContext, env: TEnv) {
+    this.ctx = ctx;
+    this.env = env;
+  }
+}
+
+export { DurableObject, RpcTarget, WorkflowEntrypoint };

package/src/vite.test.ts

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { afterAll, describe, expect, it } from 'vitest';
+import { defineWebViteConfig, spaShellEmbedPlugin } from './vite';
+
+const created: string[] = [];
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'vite-config-'));
+  created.push(root);
+  return root;
+}
+
+afterAll(() => {
+  for (const root of created) rmSync(root, { recursive: true, force: true });
+});
+
+const REAL_HTML = `<!doctype html><html><head><meta charset="utf-8" /><title>Fixture</title><script type="module" src="/assets/index-abc123.js"></script></head><body><div id="root"></div><!-- padding so the shell is a real document --></body></html>`;
+
+/** A build output: `dist/index.html` plus the bundle it references. */
+function writeBuild(root: string): void {
+  mkdirSync(join(root, 'dist', 'assets'), { recursive: true });
+  writeFileSync(join(root, 'dist', 'index.html'), REAL_HTML, 'utf8');
+  writeFileSync(join(root, 'dist', 'assets', 'index-abc123.js'), 'console.log(1)', 'utf8');
+}
+
+describe('defineWebViteConfig', () => {
+  it('empties the output directory by default', () => {
+    // A stale asset in dist is served as a live bundle, which is the same
+    // half-refreshed build verify-spa-shell rejects.
+    expect(defineWebViteConfig().build).toMatchObject({ outDir: 'dist', emptyOutDir: true });
+  });
+
+  it('passes the proxy through as data', () => {
+    const config = defineWebViteConfig({ proxy: { '/user': { target: 'http://localhost:8787', changeOrigin: true } } });
+    expect(config.server).toMatchObject({ proxy: { '/user': { target: 'http://localhost:8787' } } });
+  });
+
+  it('registers the spa-shell plugin only when a target is given', () => {
+    const withShell = defineWebViteConfig({ plugins: [], spaShell: { path: 'apps/api/src/generated/spa-shell.ts' } });
+    const without = defineWebViteConfig({ plugins: [] });
+    expect(withShell.plugins?.map((plugin) => plugin.name)).toContain('spa-shell-embed');
+    expect(without.plugins ?? []).toStrictEqual([]);
+  });
+});
+
+describe('spaShellEmbedPlugin', () => {
+  it('writes the generated module from the built index.html', async () => {
+    const root = tempRoot();
+    writeBuild(root);
+
+    const plugin = spaShellEmbedPlugin({ path: 'apps/api/src/generated/spa-shell.ts', root });
+    await plugin.closeBundle?.();
+
+    const written = readFileSync(join(root, 'apps/api/src/generated/spa-shell.ts'), 'utf8');
+    expect(written).toContain('export const SPA_HTML: string = ');
+    expect(written).toContain('DO NOT EDIT');
+    // A verbatim copy: verify-spa-shell compares the two byte for byte.
+    expect(JSON.parse(written.slice(written.indexOf('= ') + 2, written.lastIndexOf(';')).trim())).toBe(REAL_HTML);
+  });
+
+  it('skips a build that emitted no index.html, rather than failing it', () => {
+    const root = tempRoot();
+    const plugin = spaShellEmbedPlugin({ path: 'apps/api/src/generated/spa-shell.ts', root });
+    // closeBundle runs on every build, including library builds with no HTML.
+    expect(() => plugin.closeBundle?.()).not.toThrow();
+    expect(existsSync(join(root, 'apps/api/src/generated/spa-shell.ts'))).toBe(false);
+  });
+
+  it('resolves against the build directory, never against this module', async () => {
+    const root = tempRoot();
+    writeBuild(root);
+    mkdirSync(dirname(join(root, 'apps/api/src/generated')), { recursive: true });
+
+    const plugin = spaShellEmbedPlugin({ path: 'apps/api/src/generated/spa-shell.ts', root });
+    await plugin.closeBundle?.();
+
+    expect(existsSync(join(root, 'apps/api/src/generated/spa-shell.ts'))).toBe(true);
+    // The kit's own directory must not gain a generated file from a consumer's build.
+    expect(existsSync(join(process.cwd(), 'apps/api/src/generated/spa-shell.ts'))).toBe(false);
+  });
+});

package/src/vite.ts

@@ -0,0 +1,202 @@
+/**
+ * The SPA's Vite config.
+ *
+ * Provenance: converged from the `apps/web/vite.config.ts` of the eight repos
+ * that build a Vite SPA. They are one file with three variables: the plugin list
+ * (`@vitejs/plugin-react` + `@tailwindcss/vite`), the dev-server proxy target,
+ * and the `spa-shell-embed` plugin that copies `dist/index.html` into
+ * `apps/api/src/generated/spa-shell.ts`.
+ *
+ * Canonical decisions:
+ *
+ * 1. **The plugins are passed in, not imported.** The kit stays zero-dependency:
+ *   `react`, `@vitejs/plugin-react` and `@tailwindcss/vite` belong to the app
+ *   that uses them, and importing them here would make the tooling package
+ *   undownloadable for a consumer without a React SPA.
+ * 2. **The `spa-shell-embed` hook stays per-repo, and is passed in.** It is the
+ *   one genuinely repo-specific piece: each repo names its own worker and its
+ *   own generated-module path. What the kit provides is the *contract* — see
+ *   `spaShellEmbedPlugin`, which is the converged body of all eight copies.
+ * 3. **`server.proxy` is data, not code.** The paths differ per repo
+ *   (`/user` + `/rest` in Edge-Sonic, `/api` in CalDAV-Bridge, `/tracker` in
+ *   ChordDHT-Tracker) but the shape never does, so it is an option with a
+ *   default.
+ * 4. **`build.emptyOutDir: true`** is the default, because a stale asset in
+ *   `dist/` is served as a live bundle — the same half-refreshed build
+ *   `scripts/verify-spa-shell.ts` rejects.
+ *
+ * The consumer's `apps/web/vite.config.ts` becomes a handful of lines — see the
+ * README.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { defineConfig, type Plugin } from 'vitest/config';
+
+/**
+ * One dev-server proxy entry, as Vite's `server.proxy` accepts it.
+ */
+export interface ProxyEntry {
+  readonly target: string;
+  readonly changeOrigin?: boolean;
+  readonly bypass?: (request: { headers: Record<string, string | string[] | undefined> }) => string | undefined;
+}
+
+/**
+ * Where the SPA's built `index.html` is copied to, and under what module name.
+ */
+export interface SpaShellTarget {
+  /**
+   * Path of the generated module, relative to the repository root.
+   *
+   * `apps/api/src/generated/spa-shell.ts` in every repo that embeds a shell; the
+   * parameter exists because the path is the one thing that genuinely differs.
+   */
+  readonly path: string;
+  /**
+   * The repository root the path is resolved against, as a file URL or a path.
+   *
+   * Defaults to the directory the build runs in (`process.cwd()`), which is the
+   * repo root when the build is `pnpm --filter @scope/web build`. Passed in by the
+   * Vite config, not derived from `import.meta.url`: this plugin object is created
+   * inside the kit's own module, so a URL relative to it points into
+   * `node_modules/@rexezuge/tooling` and writes the shell somewhere no compiler
+   * will ever look.
+   */
+  readonly root?: string | URL;
+  /**
+   * The built `index.html`, as a path or file URL.
+   *
+   * Defaults to `dist/index.html` under the same root. Vite's `closeBundle` runs
+   * after the bundle is written, so this is the file the build just produced.
+   */
+  readonly distIndex?: string | URL;
+}
+
+/**
+ * What `defineWebViteConfig` accepts.
+ */
+export interface WebViteConfigOptions {
+  /**
+   * The SPA's plugins — `react()`, `tailwindcss()`, and anything else the app
+   * needs. Applied before the spa-shell plugin so the shell is written after the
+   * bundle exists.
+   */
+  readonly plugins?: readonly Plugin[];
+  /**
+   * Dev-server proxy entries. Keyed by path prefix.
+   */
+  readonly proxy?: Readonly<Record<string, ProxyEntry>>;
+  /**
+   * Where the built shell is embedded. Omit to skip the embedding entirely.
+   */
+  readonly spaShell?: SpaShellTarget;
+  /**
+   * The build output directory.
+   */
+  readonly outDir?: string;
+  /**
+   * The directory this config is resolved from, as a file URL. Defaults to the
+   * caller's location.
+   */
+  readonly root?: string;
+}
+
+/**
+ * The `spa-shell-embed` plugin, converged from all eight copies.
+ *
+ * It exists because the API worker serves `SPA_HTML` from a module in its own
+ * source tree, and both that module and `dist/` are gitignored — so a fresh
+ * clone gets an empty stub from `postinstall` and every `GET /` returns a blank
+ * page until someone runs a build. This plugin is what makes the build write the
+ * real artefact, and `scripts/verify-spa-shell.ts` is what refuses to deploy
+ * without it.
+ *
+ * Written as a factory rather than inlined so the exit conditions are in one
+ * place: the `closeBundle` hook runs on every build, including the ones where
+ * `dist/index.html` was never produced, and a plugin that throws there fails
+ * builds that legitimately emit nothing.
+ */
+/**
+ * Normalise a path-or-URL option to a URL, so `new URL(...)` can be used on it.
+ *
+ * Small, and here because two options accept either form: a path is what a consumer
+ * naturally writes in a config, and a URL is what `import.meta.url` hands them.
+ * Accepting both is one line and saves a `fileURLToPath` at every call site.
+ */
+function toUrl(value: string | URL): URL {
+  return typeof value === 'string' ? pathToFileURL(value) : value;
+}
+
+/**
+ * The same, as a **directory** URL — with the trailing separator `new URL(rel, base)`
+ * needs.
+ *
+ * `new URL('apps/api/x.ts', 'file:///repo')` resolves to `/apps/api/x.ts`, silently
+ * dropping the base. The base has to end in a separator, and a path from
+ * `process.cwd()` never does, so this is where the plugin would otherwise write the
+ * shell into the filesystem root.
+ */
+function toDirUrl(value: string | URL): URL {
+  const url = toUrl(value);
+  return url.href.endsWith('/') ? url : new URL(`${url.href}/`);
+}
+
+export function spaShellEmbedPlugin(target: SpaShellTarget): Plugin {
+  return {
+    name: 'spa-shell-embed',
+    closeBundle() {
+      // Resolved from the directory the build runs in, never from this module's own
+      // URL: the plugin object is created here but executes in the consumer's Vite
+      // process, and `new URL(path, import.meta.url)` would resolve against
+      // `node_modules/@rexezuge/tooling`. `process.cwd()` is the repo root for
+      // `pnpm --filter @scope/web build`, which is how every consumer runs it.
+      const root = toDirUrl(target.root ?? process.cwd());
+      const outputPath = fileURLToPath(new URL(target.path, root));
+      const indexPath = target.distIndex === undefined ? fileURLToPath(new URL('dist/index.html', root)) : fileURLToPath(toUrl(target.distIndex));
+
+      if (!existsSync(indexPath)) {
+        console.warn('spa-shell-embed: dist/index.html not found, skipping');
+        return;
+      }
+
+      const html = readFileSync(indexPath, 'utf8');
+      const output = `// Auto-generated by Vite build plugin - DO NOT EDIT.\nexport const SPA_HTML: string = ${JSON.stringify(html)};\n`;
+
+      mkdirSync(dirname(outputPath), { recursive: true });
+      writeFileSync(outputPath, output);
+    },
+  };
+}
+
+/**
+ * Build the SPA's Vite config.
+ *
+ * ```ts
+ * // apps/web/vite.config.ts
+ * import react from '@vitejs/plugin-react';
+ * import { defineWebViteConfig, spaShellEmbedPlugin } from '@rexezuge/tooling/vite';
+ *
+ * export default defineWebViteConfig({
+ *   plugins: [react()],
+ *   proxy: { '/user': { target: 'http://localhost:8787', changeOrigin: true } },
+ *   spaShell: { path: '../../apps/api/src/generated/spa-shell.ts' },
+ * });
+ * ```
+ */
+export function defineWebViteConfig(options: WebViteConfigOptions = {}): ReturnType<typeof defineConfig> {
+  const plugins: Plugin[] = [...(options.plugins ?? [])];
+  if (options.spaShell !== undefined) {
+    plugins.push(spaShellEmbedPlugin(options.spaShell));
+  }
+
+  return defineConfig({
+    ...(plugins.length > 0 && { plugins }),
+    ...(options.proxy !== undefined && { server: { proxy: { ...options.proxy } } }),
+    build: {
+      outDir: options.outDir ?? 'dist',
+      emptyOutDir: true,
+    },
+  });
+}