@rexezuge/tooling 0.0.0-stage → 1.0.0

package/dist/vite.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { 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;
+}
+export declare function spaShellEmbedPlugin(target: SpaShellTarget): Plugin;
+/**
+ * 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 declare function defineWebViteConfig(options?: WebViteConfigOptions): ReturnType<typeof defineConfig>;
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;KAAE,KAAK,MAAM,GAAG,SAAS,CAAC;CAC/G;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACtD;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AA0CD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAyBlE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAcvG"}

package/dist/vite.js

@@ -0,0 +1,125 @@
+/**
+ * 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 } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { defineConfig } from 'vitest/config';
+/**
+ * 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) {
+    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) {
+    const url = toUrl(value);
+    return url.href.endsWith('/') ? url : new URL(`${url.href}/`);
+}
+export function spaShellEmbedPlugin(target) {
+    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 = {}) {
+    const plugins = [...(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,
+        },
+    });
+}
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"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"}

package/dist/vitest-web.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The SPA's test and coverage gate.
+ *
+ * Provenance: converged from Durable-DAV-Router's and Mail-Otter's
+ * `vitest.web.config.mts`, which are the two repos that gave the frontend its own
+ * suite. Durable-DAV-Router's is the canonical shape — it is the one that records
+ * *why* the split exists; Mail-Otter's contributes the React plugin and the
+ * `apps/web/**` include.
+ *
+ * Canonical decisions:
+ *
+ * 1. **It is a separate config, not a `projects` entry in one.** With a single
+ *    config the SPA suites ran under `node` and the worker suites under `jsdom`
+ *    in the same pass, so a test could pass in one environment and fail in the
+ *    other with neither run noticing.
+ * 2. **`pool: 'threads'`, bounded, rather than one forked worker per file.** Each
+ *    jsdom document is a whole browser environment; a fork per file exhausts
+ *    memory on a constrained machine, and when it does the run dies partway with
+ *    a bare "Worker exited unexpectedly" and no test reports a failure — which
+ *    reads as a flaky suite rather than as an out-of-memory kill.
+ * 3. **jsdom is set here for every file**, rather than a `@vitest-environment`
+ *    pragma per file: these are the tests that need a DOM, and the pragma is one
+ *    more place to forget.
+ * 4. **`include` covers both shapes the repos use** — the root-suite `web-*`
+ *    naming convention and suites bundled under `apps/web` — and the same globs
+ *    are what `defineUnitVitestConfig()` excludes.
+ */
+import { defineConfig, type Plugin } from 'vitest/config';
+import type { CoverageThresholds, VitestAlias } from './vitest';
+/**
+ * What `defineWebVitestConfig` accepts.
+ */
+export interface WebVitestConfigOptions {
+    /**
+     * Vite plugins the SPA needs — `@vitejs/plugin-react` for a React app. Passed
+     * by the consumer rather than imported here, because the kit must stay
+     * zero-dependency and the plugin belongs to the app, not the harness.
+     */
+    readonly plugins?: readonly Plugin[];
+    /**
+     * Extra resolver entries.
+     */
+    readonly aliases?: readonly VitestAlias[];
+    /**
+     * The repo root, as a file URL.
+     */
+    readonly root?: string;
+    /**
+     * Which suites to collect. Defaults to both shapes the source repos use.
+     */
+    readonly include?: readonly string[];
+    /**
+     * Coverage floors. Omitted by default; see `defineUnitVitestConfig`.
+     */
+    readonly thresholds?: CoverageThresholds;
+    /**
+     * Where the coverage report is written. Separate from the unit config's, so
+     * the two gates never overwrite each other's report.
+     */
+    readonly reportsDirectory?: string;
+}
+/**
+ * Build the SPA's test config.
+ *
+ * ```ts
+ * // vitest.web.config.mts
+ * import react from '@vitejs/plugin-react';
+ * import { defineWebVitestConfig } from '@rexezuge/tooling/vitest-web';
+ * export default defineWebVitestConfig({ plugins: [react()] });
+ * ```
+ */
+export declare function defineWebVitestConfig(options?: WebVitestConfigOptions): ReturnType<typeof defineConfig>;
+//# sourceMappingURL=vitest-web.d.ts.map

package/dist/vitest-web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-web.d.ts","sourceRoot":"","sources":["../src/vitest-web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAQD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CA2B3G"}

package/dist/vitest-web.js

@@ -0,0 +1,72 @@
+/**
+ * The SPA's test and coverage gate.
+ *
+ * Provenance: converged from Durable-DAV-Router's and Mail-Otter's
+ * `vitest.web.config.mts`, which are the two repos that gave the frontend its own
+ * suite. Durable-DAV-Router's is the canonical shape — it is the one that records
+ * *why* the split exists; Mail-Otter's contributes the React plugin and the
+ * `apps/web/**` include.
+ *
+ * Canonical decisions:
+ *
+ * 1. **It is a separate config, not a `projects` entry in one.** With a single
+ *    config the SPA suites ran under `node` and the worker suites under `jsdom`
+ *    in the same pass, so a test could pass in one environment and fail in the
+ *    other with neither run noticing.
+ * 2. **`pool: 'threads'`, bounded, rather than one forked worker per file.** Each
+ *    jsdom document is a whole browser environment; a fork per file exhausts
+ *    memory on a constrained machine, and when it does the run dies partway with
+ *    a bare "Worker exited unexpectedly" and no test reports a failure — which
+ *    reads as a flaky suite rather than as an out-of-memory kill.
+ * 3. **jsdom is set here for every file**, rather than a `@vitest-environment`
+ *    pragma per file: these are the tests that need a DOM, and the pragma is one
+ *    more place to forget.
+ * 4. **`include` covers both shapes the repos use** — the root-suite `web-*`
+ *    naming convention and suites bundled under `apps/web` — and the same globs
+ *    are what `defineUnitVitestConfig()` excludes.
+ */
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'node:url';
+/**
+ * The default suite globs: the root-suite `web-*` convention and the
+ * bundled-under-`apps/web` convention, so either layout works unchanged.
+ */
+const DEFAULT_INCLUDE = ['test/**/web-*.test.{ts,tsx}', 'apps/web/**/*.test.{ts,tsx}'];
+/**
+ * Build the SPA's test config.
+ *
+ * ```ts
+ * // vitest.web.config.mts
+ * import react from '@vitejs/plugin-react';
+ * import { defineWebVitestConfig } from '@rexezuge/tooling/vitest-web';
+ * export default defineWebVitestConfig({ plugins: [react()] });
+ * ```
+ */
+export function defineWebVitestConfig(options = {}) {
+    const root = options.root ?? new URL('.', import.meta.url).href;
+    const webSrc = fileURLToPath(new URL('apps/web/src', root));
+    const aliases = [{ find: /^@\//, replacement: `${webSrc}/` }, ...(options.aliases ?? [])];
+    return defineConfig({
+        ...(options.plugins !== undefined && { plugins: [...options.plugins] }),
+        resolve: { alias: aliases },
+        test: {
+            globals: true,
+            environment: 'jsdom',
+            include: [...(options.include ?? DEFAULT_INCLUDE)],
+            // Threads, bounded, rather than one forked worker per file — see the
+            // header. A custom `exclude` replaces Vitest's defaults, so `node_modules`
+            // must be re-listed.
+            pool: 'threads',
+            exclude: ['**/node_modules/**', '**/dist/**', 'test/integration/**'],
+            coverage: {
+                provider: 'v8',
+                reporter: ['text', 'lcov'],
+                reportsDirectory: options.reportsDirectory ?? './coverage-spa',
+                include: ['apps/web/src/**/*.{ts,tsx}'],
+                exclude: ['**/*.test.{ts,tsx}', '**/*.d.ts', '**/types.ts', '**/generated/**'],
+                ...(options.thresholds !== undefined && { thresholds: { ...options.thresholds } }),
+            },
+        },
+    });
+}
+//# sourceMappingURL=vitest-web.js.map

package/dist/vitest-web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-web.js","sourceRoot":"","sources":["../src/vitest-web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,YAAY,EAAe,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAoCzC;;;GAGG;AACH,MAAM,eAAe,GAAsB,CAAC,6BAA6B,EAAE,6BAA6B,CAAC,CAAC;AAE1G;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkC,EAAE;IACxE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IAChE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAkB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,GAAG,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;IAEzG,OAAO,YAAY,CAAC;QAClB,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACvE,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;QAC3B,IAAI,EAAE;YACJ,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,OAAO;YACpB,OAAO,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC;YAClD,qEAAqE;YACrE,2EAA2E;YAC3E,qBAAqB;YACrB,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC,oBAAoB,EAAE,YAAY,EAAE,qBAAqB,CAAC;YACpE,QAAQ,EAAE;gBACR,QAAQ,EAAE,IAAI;gBACd,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;gBAC1B,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,gBAAgB;gBAC9D,OAAO,EAAE,CAAC,4BAA4B,CAAC;gBACvC,OAAO,EAAE,CAAC,oBAAoB,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,CAAC;gBAC9E,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;aACnF;SACF;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/vitest.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The unit-test Vitest config for the worker-and-packages half of the suite.
+ *
+ * Provenance: converged from the eight repos' `vitest.config.mts`. The coverage
+ * block is Durable-DAV-Router's (the most complete: v8 provider, explicit
+ * include/exclude patterns, thresholds with the reasoning for why they sit just
+ * under the measured value); the alias block is Durable-DAV's, which is the only
+ * one that also aliases `cloudflare:workers` and `cloudflare:sockets` to the
+ * Node mocks.
+ *
+ * Canonical decisions:
+ *
+ * 1. **Every file matching `include` is reported** — Vitest 4 removed
+ *    `coverage.all`, and an explicit `include` now covers files no test
+ *    imported. That is the behaviour the source repos configured `all: true` for,
+ *    and the reason it mattered: without it a brand-new module with no test is
+ *    invisible rather than counted as zero, which is the exact regression this
+ *    gate exists to catch.
+ * 2. **The SPA is excluded here**, so this config and `defineWebVitestConfig()`
+ *    partition the suite rather than each running all of it. Every SPA suite is
+ *    named `web-*`. One number could not honestly describe both halves: the SPA's
+ *    presentational modules pulled a shared floor down 16 points, so a change
+ *    adding legitimate code in `apps/api` could fail the gate on the strength of
+ *    files two directories away.
+ * 3. **A custom `exclude` re-lists `node_modules`** — `test/` is a workspace
+ *    project and therefore has its own, so without the re-list the glob reaches
+ *    into `test/node_modules` and tries to run other packages' suites.
+ * 4. **Thresholds are a consumer argument**, not a kit default. A floor is a
+ *    per-repo ratchet measured against that repo's suite; the kit cannot know a
+ *    number, and guessing one is how floors get lowered.
+ */
+import { defineConfig } from 'vitest/config';
+/**
+ * One `{ find, replacement }` pair for Vitest's resolver.
+ */
+export interface VitestAlias {
+    readonly find: string | RegExp;
+    readonly replacement: string;
+}
+/**
+ * Coverage thresholds, in the four figures Vitest gates on.
+ */
+export interface CoverageThresholds {
+    readonly statements?: number;
+    readonly branches?: number;
+    readonly functions?: number;
+    readonly lines?: number;
+}
+/**
+ * What `defineUnitVitestConfig` accepts. Every field is optional: the defaults
+ * cover the canonical monorepo layout, and a consumer overrides only what its
+ * tree actually differs in.
+ */
+export interface UnitVitestConfigOptions {
+    /**
+     * Extra resolver entries, applied after the canonical ones.
+     */
+    readonly aliases?: readonly VitestAlias[];
+    /**
+     * Where the repo root is, as a file URL. Defaults to the directory this
+     * factory is *called* from, which is the repo root's `vitest.config.mts`.
+     */
+    readonly root?: string;
+    /**
+     * Coverage `include` globs. Defaults to the worker plus every workspace
+     * package's `src`.
+     */
+    readonly coverageInclude?: readonly string[];
+    /**
+     * Coverage `exclude` globs, merged with the canonical set.
+     */
+    readonly coverageExclude?: readonly string[];
+    /**
+     * Coverage floors. Omitted by default; a repo that wants them sets them.
+     */
+    readonly thresholds?: CoverageThresholds;
+    /**
+     * Where the coverage report is written.
+     */
+    readonly reportsDirectory?: string;
+}
+/**
+ * Build the unit-test config.
+ *
+ * ```ts
+ * // vitest.config.mts
+ * import { defineUnitVitestConfig } from '@rexezuge/tooling/vitest';
+ * export default defineUnitVitestConfig();
+ * ```
+ */
+export declare function defineUnitVitestConfig(options?: UnitVitestConfigOptions): ReturnType<typeof defineConfig>;
+//# sourceMappingURL=vitest.d.ts.map

package/dist/vitest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.d.ts","sourceRoot":"","sources":["../src/vitest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;OAEG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IACzC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAmDD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAuC7G"}

package/dist/vitest.js

@@ -0,0 +1,128 @@
+/**
+ * The unit-test Vitest config for the worker-and-packages half of the suite.
+ *
+ * Provenance: converged from the eight repos' `vitest.config.mts`. The coverage
+ * block is Durable-DAV-Router's (the most complete: v8 provider, explicit
+ * include/exclude patterns, thresholds with the reasoning for why they sit just
+ * under the measured value); the alias block is Durable-DAV's, which is the only
+ * one that also aliases `cloudflare:workers` and `cloudflare:sockets` to the
+ * Node mocks.
+ *
+ * Canonical decisions:
+ *
+ * 1. **Every file matching `include` is reported** — Vitest 4 removed
+ *    `coverage.all`, and an explicit `include` now covers files no test
+ *    imported. That is the behaviour the source repos configured `all: true` for,
+ *    and the reason it mattered: without it a brand-new module with no test is
+ *    invisible rather than counted as zero, which is the exact regression this
+ *    gate exists to catch.
+ * 2. **The SPA is excluded here**, so this config and `defineWebVitestConfig()`
+ *    partition the suite rather than each running all of it. Every SPA suite is
+ *    named `web-*`. One number could not honestly describe both halves: the SPA's
+ *    presentational modules pulled a shared floor down 16 points, so a change
+ *    adding legitimate code in `apps/api` could fail the gate on the strength of
+ *    files two directories away.
+ * 3. **A custom `exclude` re-lists `node_modules`** — `test/` is a workspace
+ *    project and therefore has its own, so without the re-list the glob reaches
+ *    into `test/node_modules` and tries to run other packages' suites.
+ * 4. **Thresholds are a consumer argument**, not a kit default. A floor is a
+ *    per-repo ratchet measured against that repo's suite; the kit cannot know a
+ *    number, and guessing one is how floors get lowered.
+ */
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'node:url';
+/**
+ * The SPA's suites, excluded here so the two configs partition the suite.
+ *
+ * Every SPA suite is named `web-*`. `defineWebVitestConfig()` includes the same
+ * glob, so a file is collected by exactly one config.
+ */
+const SPA_FILES = 'test/**/web-*.test.{ts,tsx}';
+/**
+ * The canonical alias set.
+ *
+ * Built relative to the consumer's repo root rather than the kit's directory,
+ * so the factory describes *their* layout. A Vitest config is a standalone file
+ * with no module graph to share through, and a suite resolving a workspace
+ * import differently from its sibling fails in a way that looks like a product
+ * bug — which is why these are stated once, here, rather than duplicated.
+ */
+function canonicalAliases(root) {
+    const at = (relative) => fileURLToPath(new URL(relative, root));
+    return [
+        { find: 'cloudflare:workers', replacement: at('test/mocks/cloudflare-workers.ts') },
+        { find: 'cloudflare:sockets', replacement: at('test/mocks/cloudflare-sockets.ts') },
+        { find: /^@\//, replacement: `${at('apps/api/src')}/` },
+        { find: /^~\//, replacement: `${at('apps/web/src')}/` },
+    ];
+}
+/**
+ * Coverage `exclude` globs converged from the source repos.
+ *
+ * The categories: build and test tooling (`scripts/` grows with project surface,
+ * not complexity, and the god-file guard excludes it for the same reason), test
+ * files, declarations, re-export barrels (`index.ts` carries no logic of its
+ * own), model records, generated files (the SPA shell is a one-line HTML blob
+ * with no logic to exercise), and type-only modules.
+ */
+const CANONICAL_COVERAGE_EXCLUDE = [
+    'scripts/**',
+    '**/*.test.ts',
+    '**/*.d.ts',
+    '**/index.ts',
+    '**/types.d.ts',
+    '**/model/**',
+    '**/generated/**',
+    '**/D1Types.ts',
+    '**/ServiceEnv.ts',
+    '**/env.d.ts',
+];
+/**
+ * Build the unit-test config.
+ *
+ * ```ts
+ * // vitest.config.mts
+ * import { defineUnitVitestConfig } from '@rexezuge/tooling/vitest';
+ * export default defineUnitVitestConfig();
+ * ```
+ */
+export function defineUnitVitestConfig(options = {}) {
+    const root = options.root ?? new URL('.', import.meta.url).href;
+    const coverageInclude = options.coverageInclude ?? ['apps/api/src/**/*.ts', 'apps/background/src/**/*.ts', 'packages/**/src/**/*.ts'];
+    const coverageExclude = [...CANONICAL_COVERAGE_EXCLUDE, ...(options.coverageExclude ?? [])];
+    const aliases = [...canonicalAliases(root), ...(options.aliases ?? [])];
+    return defineConfig({
+        resolve: { alias: aliases },
+        test: {
+            globals: true,
+            environment: 'node',
+            include: ['test/**/*.test.{ts,tsx}'],
+            // `test` is a workspace project and therefore has its own node_modules;
+            // without the re-list, the glob reaches into it.
+            exclude: ['**/node_modules/**', '**/dist/**', 'test/integration/**', SPA_FILES],
+            server: {
+                deps: {
+                    // A `node_modules` dependency is externalized by default, so Node's
+                    // own ESM loader resolves a `cloudflare:workers` specifier and rejects
+                    // the scheme before `resolve.alias` is ever consulted. Inlining routes
+                    // it back through Vite, where the alias applies.
+                    inline: ['dofs'],
+                },
+            },
+            coverage: {
+                provider: 'v8',
+                // Vitest 4 removed `coverage.all`; an explicit `include` now reports
+                // every matching file whether or not a test imported it, which is the
+                // behaviour the source repos' `all: true` was there to get: a brand-new
+                // module with no test is counted as zero rather than being invisible,
+                // which is the exact regression this gate exists to catch.
+                reporter: ['text', 'lcov', 'html'],
+                reportsDirectory: options.reportsDirectory ?? './coverage',
+                include: [...coverageInclude],
+                exclude: coverageExclude,
+                ...(options.thresholds !== undefined && { thresholds: { ...options.thresholds } }),
+            },
+        },
+    });
+}
+//# sourceMappingURL=vitest.js.map

package/dist/vitest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.js","sourceRoot":"","sources":["../src/vitest.ts"],"names":[],"mappings":"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"}