tempest-react-sdk 0.81.0 → 0.83.0

package/README.md

@@ -159,7 +159,7 @@ Via `package.json`:
 
 Requires React `>=18` and Node `>=22.12` to build.
 
-**A bundler is assumed — outside one, load the shipped `.css` loader.** Every component module imports its own stylesheet (see [CSS import](#css-import)), and `.css` is not a format Node can load — `node -e "import('tempest-react-sdk')"` fails with `ERR_UNKNOWN_FILE_EXTENSION`. Vite, webpack, Rspack, Parcel and esbuild all resolve that import, and the SDK is client-side only, so no real app consumer is affected. For everything that is not a bundler — a script, a Jest suite, reading the surface by introspection — the package ships the loader: `node --import tempest-react-sdk/node-css-loader your-script.mjs` resolves every stylesheet to an empty module, for `import` and `require` both. A **Jest** suite can use it or the usual `moduleNameMapper: { "\\.css$": "<rootDir>/test/css-stub.js" }`. Vitest needs nothing.
+**A bundler is assumed — outside one, load the shipped `.css` loader.** Every component module imports its own stylesheet (see [CSS import](#css-import)), and `.css` is not a format Node can load — `node -e "import('tempest-react-sdk')"` fails with `ERR_UNKNOWN_FILE_EXTENSION`. Vite, webpack, Rspack, Parcel and esbuild all resolve that import, and the SDK is client-side only, so no real app consumer is affected. For everything that is not a bundler — a script, a Jest suite, reading the surface by introspection — the package ships the loader: `node --import tempest-react-sdk/node-css-loader your-script.mjs` resolves every stylesheet to an empty module, for `import` and `require` both. A **Jest** suite can use it or the usual `moduleNameMapper: { "\\.css$": "<rootDir>/test/css-stub.js" }`. **Vitest** needs `tempestVitest()` from `tempest-react-sdk/vite`, because it hands every ESM package from `node_modules` to Node: `createViteConfig` already wires it, but a separate `vitest.config.ts` (or a plain `vite.config.ts`) must add it to `plugins`, or the first import of the SDK fails with `Unknown file extension ".css"` — see [Testing with Vitest](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/vite-config/#testing-with-vitest).
 
 ### Peer & bundled dependencies
 
@@ -276,7 +276,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `router` _(dep: `react-router`)_                                                                  | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports of React Router's whole client-side surface (`Link`, `NavLink`, `Outlet`, `useNavigate`, `useParams`, `useSearchParams`, `matchPath`, `generatePath`, `createBrowserRouter`, `useLoaderData`, …; its `Form` as `RouterForm`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `store` _(dep: `zustand`)_                                                                        | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `app`                                                                                             | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestCsp` (writes a Content-Security-Policy whose `connect-src` is derived from the app's `VITE_*` URLs, enforced in dev too), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `TempestCspOptions`, `TempestCspPolicy`, `TempestCspSource`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                                                                                                                  |
+| `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev` and bundles it into `vite build`), `tempestCsp` (writes a Content-Security-Policy whose `connect-src` is derived from the app's `VITE_*` URLs, enforced in dev too), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `TempestCspOptions`, `TempestCspPolicy`, `TempestCspSource`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                                                                                 |
 | `forms` _(peer: `zod`, `react-hook-form`)_                                                        | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `sse`                                                                                             | `createEventStream`, `useEventStream` (`schema` valida cada frame — zod/valibot/arktype via Standard Schema — e `onParseError` para frame que não é JSON)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `ws`                                                                                              | `createWebSocket` (handshake timeout, silence watchdog, jittered backoff, `navigator.onLine` suspend, close-code classification, `opened` promise), `useWebSocket`, `schema` + `onValidationError` (frame fora do contrato não é entregue; o `pong` do heartbeat continua saindo), `onParseError` (frame que não é JSON: descarta em vez de entregar `string` como `T`), `isRejectionCloseCode`, `HEARTBEAT_CLOSE_CODE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -312,7 +312,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `router` _(dep: `react-router`)_                                                                  | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports of React Router's whole client-side surface (`Link`, `NavLink`, `Outlet`, `useNavigate`, `useParams`, `useSearchParams`, `matchPath`, `generatePath`, `createBrowserRouter`, `useLoaderData`, …; its `Form` as `RouterForm`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `store` _(dep: `zustand`)_                                                                        | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `app`                                                                                             | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev` and bundles it into `vite build`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `forms` _(peer: `zod`, `react-hook-form`)_                                                        | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `sse`                                                                                             | `createEventStream`, `useEventStream` (`schema` valida cada frame — zod/valibot/arktype via Standard Schema — e `onParseError` para frame que não é JSON)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `ws`                                                                                              | `createWebSocket` (handshake timeout, silence watchdog, jittered backoff, `navigator.onLine` suspend, close-code classification, `opened` promise), `useWebSocket`, `schema` + `onValidationError` (frame fora do contrato não é entregue; o `pong` do heartbeat continua saindo), `onParseError` (frame que não é JSON: descarta em vez de entregar `string` como `T`), `isRejectionCloseCode`, `HEARTBEAT_CLOSE_CODE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -343,7 +343,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 
 Full per-module docs are published as a bilingual MkDocs site on GitHub Pages — **[Português (BR)](https://mauriciobenjamin700.github.io/tempest-react-sdk/)** / **[English (US)](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/)** (one page per module + draw.io diagrams in [`docs/diagrams/`](./docs/diagrams)). The source markdown lives in [`docs/`](./docs) (PT-BR base files + `.en.md` translations).
 
-> **Local preview:** `pip install -r docs/requirements.txt && mkdocs serve` (the published site is built and deployed automatically by `.github/workflows/docs.yml`).
+> **Local preview:** `pip install -r docs/requirements.txt && mkdocs serve` (the published site is built and pushed to `gh-pages` by `make docs-deploy`, from the maintainer's machine).
 
 A demo app exercising every module lives in [`examples/gallery`](./examples/gallery) — `cd examples/gallery && npm install && npm run dev`.
 
@@ -1321,7 +1321,7 @@ installNotificationClickHandler({
 });
 ```
 
-The SDK does **not** ship the worker file or the bundler config — pair it with `vite-plugin-pwa` (`injectManifest`) or a separately bundled worker.
+The SDK does **not** ship the worker file — you write `src/sw.ts`. `tempestPwaDevSw()` from `tempest-react-sdk/vite` bundles it to `dist/sw.js` in `vite build` (and serves it in dev), and `tempestPwaManifest()` fails the build when the manifest would ship without a worker. See [Vite Config › PWA](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/vite-config/#pwa-the-service-worker-in-the-production-build).
 
 ### Audio playback recipe
 
@@ -1995,15 +1995,14 @@ Every gallery section maps 1-to-1 with a docs page — see [`docs/gallery.md`](.
 
 ## Release
 
-Versioning is managed with [Changesets](https://github.com/changesets/changesets):
+Two commands, with the release PR's review in between:
 
 ```bash
-npx changeset          # describe the change (patch / minor / major)
-npx changeset version  # bump versions + update CHANGELOG.md
-npm run release        # build + changeset publish
+make release TAG=X.Y.Z       # opens the release PR (no tag, no publish)
+make release-tag TAG=X.Y.Z   # after the merge: build + smokes + npm publish + tag + GitHub Release
 ```
 
-CI workflow `.github/workflows/release.yml` publishes to npm whenever a "Version Packages" PR merges into `main`. The first publish is manual — set the `NPM_TOKEN` secret in _Settings → Secrets and variables → Actions_ and run `npm publish` once.
+There is no GitHub Actions in this repository: `make release-tag` runs the ref guard, builds and smokes the merged commit, publishes the smoked tarball with the maintainer's npm credential (no provenance — that needs a CI runner's OIDC), pushes the tag and creates the GitHub Release. A bare `npm publish` is refused (`make publish` exits 1). Pipeline and the repository owner's settings checklist: [Release pipeline](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/release/).
 
 Tags follow `vMAJOR.MINOR.PATCH`. CSS tokens (`--tempest-*`) are treated as public API — renames bump the minor (or major, on removal).
 

package/bin/create-tempest-app.e2e.test.mjs

@@ -49,6 +49,37 @@ function scaffoldHere() {
     return { status: result.status, stdout: result.stdout + result.stderr };
 }
 
+describe("create-tempest-app new-folder mode refuses a destination that is a symlink (#533)", () => {
+    it("my-app -> ../outside is refused and nothing lands at the link target", () => {
+        symlinkSync("../outside", join(proj, "my-app"));
+
+        const result = spawnSync(process.execPath, [CLI, "my-app"], {
+            cwd: proj,
+            encoding: "utf8",
+            env: { ...process.env, NO_COLOR: "1" },
+        });
+
+        expect(result.status).toBe(1);
+        expect(result.stderr).toMatch(/"my-app" is a symbolic link/);
+        expect(readdirSync(outside)).toEqual([]);
+        expect(lstatSync(join(proj, "my-app")).isSymbolicLink()).toBe(true);
+    });
+
+    it("a plain new folder name is still scaffolded", () => {
+        const result = spawnSync(process.execPath, [CLI, "my-app"], {
+            cwd: proj,
+            encoding: "utf8",
+            env: { ...process.env, NO_COLOR: "1" },
+        });
+
+        expect(result.status).toBe(0);
+        expect(existsSync(join(proj, "my-app", "src", "main.tsx"))).toBe(true);
+        expect(JSON.parse(readFileSync(join(proj, "my-app", "package.json"), "utf8")).name).toBe(
+            "my-app",
+        );
+    });
+});
+
 describe("create-tempest-app merge mode never writes through a symlink (#436)", () => {
     it("a symlinked src/ pointing outside the project is skipped, not written into", () => {
         writeFileSync(join(outside, "main.tsx"), "OUTSIDE-USER-FILE");

package/bin/create-tempest-app.mjs

@@ -10,7 +10,8 @@
 // package.json has the Tempest scripts/deps merged in (your name/version are
 // preserved). A symlink already in the destination is never written through:
 // it is skipped and reported, so a link to a folder outside the project cannot
-// redirect the template there. The `--pwa` flag overlays the PWA template
+// redirect the template there. A named destination that is itself a symlink is
+// refused for the same reason. The `--pwa` flag overlays the PWA template
 // (manifest, service worker, push-subscribe wiring) on top of the base.
 import { cp, lstat, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -239,6 +240,15 @@ async function main() {
             process.exit(1);
         }
         destDir = resolve(process.cwd(), arg);
+        if (await isSymlink(destDir)) {
+            console.error(
+                `${c.red}✗ "${arg}" is a symbolic link; the project would be created where it points.${c.reset}`,
+            );
+            console.error(
+                `${c.dim}  Create the project at the real path, or remove the link.${c.reset}`,
+            );
+            process.exit(1);
+        }
         if (!(await isEmptyDir(destDir))) {
             console.error(`${c.red}✗ Directory "${arg}" exists and is not empty.${c.reset}`);
             console.error(

package/bin/lib/doctor/doctor.e2e.test.mjs

@@ -98,6 +98,11 @@ describe("tempest doctor — a third-party project that does not use the SDK", (
         expect(out).not.toContain('add import "tempest-react-sdk/styles.css"');
     });
 
+    it("does not judge the Vitest config of a project without the SDK", () => {
+        installed("vitest", "4.1.12");
+        expect(doctor().out).not.toContain("inline the SDK");
+    });
+
     it("does not demand a src/main.tsx it has no reason to expect", () => {
         const { out } = doctor();
         expect(out).not.toContain("app entry");
@@ -336,6 +341,30 @@ describe("tempest doctor — a project that does use the SDK", () => {
         expect(doctor().out).toContain("leaflet missing");
     });
 
+    it("warns when Vitest would load the SDK without the plugin", () => {
+        installed("vitest", "4.1.12");
+        const { out, code } = doctor();
+        expect(out).toContain("vite.config.ts does not inline the SDK for Vitest");
+        expect(out).toContain("tempestVitest()");
+        expect(code).toBe(0);
+    });
+
+    it("accepts a vitest.config that adds tempestVitest", () => {
+        installed("vitest", "4.1.12");
+        write(
+            "vitest.config.ts",
+            'import { tempestVitest } from "tempest-react-sdk/vite";\n' +
+                "export default defineConfig({ plugins: [tempestVitest()] });",
+        );
+        const { out } = doctor();
+        expect(out).toContain("vitest.config.ts lets Vitest load the SDK");
+        expect(out).not.toContain("does not inline the SDK");
+    });
+
+    it("says nothing about Vitest in a project that does not install it", () => {
+        expect(doctor().out).not.toContain("Vitest");
+    });
+
     it("warns when the SDK is installed but undeclared", () => {
         write("package.json", {
             name: "sdk-app",

package/bin/lib/doctor/vitest.mjs

@@ -0,0 +1,120 @@
+/**
+ * The Vitest config check for `tempest doctor`.
+ *
+ * Every SDK component module imports its own stylesheet, and Vitest hands an ESM
+ * package from `node_modules` to plain Node, which has no loader for `.css`. A
+ * consumer suite that imports the SDK therefore dies before running with
+ * `Unknown file extension ".css"` unless the config inlines the SDK — which is what
+ * `tempestVitest()` does, and what `createViteConfig` includes. Measured in #548
+ * with the 0.81.0 tarball on Vitest 4.1.12: an own `vitest.config.ts`, a plain
+ * `vite.config.ts` and no config at all fail; only the plugin passes.
+ *
+ * The check is a text heuristic over the config file Vitest would load, not an
+ * evaluation of it: running the user's config would execute their code and pull
+ * their plugins in, which a health check has no business doing. The markers are the
+ * plugin and helper names, an explicit `inline: true` (which inlines everything,
+ * the SDK included), and an inline list naming the package — the three shapes that
+ * make the suite pass.
+ */
+
+/**
+ * Config file names Vitest looks for, in the order it prefers them.
+ *
+ * Ported from Vitest 4.1.12's `configFiles` (`CONFIG_NAMES` × `CONFIG_EXTENSIONS`
+ * in `dist/chunks/constants.*.js`, not exported): a `vitest.config.*` wins over a
+ * `vite.config.*`, and within each the extensions are tried in this order. The
+ * test reads the installed Vitest and fails when the list drifts.
+ */
+export const VITEST_CONFIG_FILES = [
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "vitest.config.cts",
+    "vitest.config.js",
+    "vitest.config.mjs",
+    "vitest.config.cjs",
+    "vite.config.ts",
+    "vite.config.mts",
+    "vite.config.cts",
+    "vite.config.js",
+    "vite.config.mjs",
+    "vite.config.cjs",
+];
+
+/** Text that, once comments are gone, means the config already inlines the SDK. */
+const INLINES_SDK = [
+    /\btempestVitest\b/,
+    /\bcreateViteConfig\b/,
+    /\binline\s*:\s*true\b/,
+    /\binline\s*:\s*\[[^\]]*["'`]tempest-react-sdk["'`]/,
+];
+
+/** An import of the project's own `vite.config`, as `mergeConfig` setups do. */
+const IMPORTS_VITE_CONFIG = /from\s*["']\.\/vite\.config(?:\.[cm]?[jt]s)?["']/;
+
+/**
+ * Drop JavaScript comments so a marker that only appears in prose does not count.
+ *
+ * A line comment is only removed when `//` is not preceded by `:`, which keeps
+ * `https://` inside a string intact; a missed edge case here costs one false "ok",
+ * never a crash.
+ *
+ * @param {string} text - Source text of a config file.
+ * @returns {string} The text without block and line comments.
+ */
+function stripComments(text) {
+    return text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+
+/**
+ * Whether a config file's text makes Vitest inline the SDK.
+ *
+ * @param {string} text - Source text of the config.
+ * @returns {boolean} Whether one of the passing shapes is present.
+ */
+function inlinesSdk(text) {
+    const code = stripComments(text);
+    return INLINES_SDK.some((marker) => marker.test(code));
+}
+
+/**
+ * Audit whether the project's Vitest setup can import the SDK.
+ *
+ * Vitest loads the first `vitest.config.*`, else the first `vite.config.*`, else
+ * runs with defaults; this mirrors that choice and judges only the file it would
+ * load. A `vitest.config.*` that imports `./vite.config` (the `mergeConfig`
+ * pattern) passes when that `vite.config.*` does, so a project using
+ * `createViteConfig` there is not flagged.
+ *
+ * @param {object} params
+ * @param {boolean} params.vitestInstalled - Whether `vitest` resolves in the project.
+ * @param {Record<string, string>} params.configs - Text of each config file present,
+ *   keyed by its name from {@link VITEST_CONFIG_FILES}.
+ * @returns {Array<[status: string, label: string, detail?: string]>} Check rows;
+ *   empty when the project does not use Vitest.
+ */
+export function checkVitest({ vitestInstalled, configs }) {
+    if (!vitestInstalled) return [];
+
+    const loaded = VITEST_CONFIG_FILES.find((name) => name in configs);
+    const fix =
+        "add `plugins: [tempestVitest()]` from tempest-react-sdk/vite, or build the config " +
+        "with createViteConfig — otherwise any test importing the SDK fails with " +
+        '`Unknown file extension ".css"`';
+
+    if (!loaded) {
+        return [["warn", "Vitest runs with no config", fix]];
+    }
+
+    const text = configs[loaded];
+    const viaViteConfig =
+        loaded.startsWith("vitest.") &&
+        IMPORTS_VITE_CONFIG.test(stripComments(text)) &&
+        VITEST_CONFIG_FILES.some(
+            (name) => name.startsWith("vite.") && name in configs && inlinesSdk(configs[name]),
+        );
+
+    if (inlinesSdk(text) || viaViteConfig) {
+        return [["ok", `${loaded} lets Vitest load the SDK`]];
+    }
+    return [["warn", `${loaded} does not inline the SDK for Vitest`, fix]];
+}

package/bin/lib/doctor/vitest.test.mjs

@@ -0,0 +1,139 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { VITEST_CONFIG_FILES, checkVitest } from "./vitest.mjs";
+
+const VITEST_CHUNKS = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "..",
+    "node_modules",
+    "vitest",
+    "dist",
+    "chunks",
+);
+
+/** Statuses of the returned rows, in order. */
+const statuses = (rows) => rows.map(([status]) => status);
+
+/** Run the check for a project with Vitest and the given config files. */
+const check = (configs) => checkVitest({ vitestInstalled: true, configs });
+
+/**
+ * The config file list the installed Vitest really searches, read from its source.
+ *
+ * @returns {string[]} `CONFIG_NAMES` × `CONFIG_EXTENSIONS`, in Vitest's order.
+ */
+function installedVitestConfigFiles() {
+    const file = readdirSync(VITEST_CHUNKS).find((name) => /^constants\..*\.js$/.test(name));
+    const text = readFileSync(join(VITEST_CHUNKS, file), "utf8");
+    const array = (name) =>
+        JSON.parse(
+            new RegExp(`const ${name} = (\\[[^\\]]*\\])`)
+                .exec(text)[1]
+                .replace(/\s+/g, "")
+                .replace(/,]/, "]"),
+        );
+    return array("CONFIG_NAMES").flatMap((name) =>
+        array("CONFIG_EXTENSIONS").map((ext) => name + ext),
+    );
+}
+
+describe("checkVitest — which file it judges", () => {
+    it("searches the same files, in the same order, as the installed Vitest", () => {
+        expect(VITEST_CONFIG_FILES).toEqual(installedVitestConfigFiles());
+    });
+
+    it("judges vitest.config over vite.config, the one Vitest loads", () => {
+        const rows = check({
+            "vite.config.ts": "export default createViteConfig();",
+            "vitest.config.ts": "export default defineConfig({ test: {} });",
+        });
+        expect(statuses(rows)).toEqual(["warn"]);
+        expect(rows[0][1]).toContain("vitest.config.ts");
+    });
+
+    it("falls back to vite.config when there is no vitest.config", () => {
+        const rows = check({ "vite.config.mjs": "export default defineConfig({});" });
+        expect(rows[0][1]).toContain("vite.config.mjs");
+    });
+});
+
+describe("checkVitest — setups that fail the suite", () => {
+    it("says nothing when the project does not use Vitest", () => {
+        expect(checkVitest({ vitestInstalled: false, configs: {} })).toEqual([]);
+    });
+
+    it("warns when Vitest would run with no config at all", () => {
+        const rows = check({});
+        expect(statuses(rows)).toEqual(["warn"]);
+        expect(rows[0][2]).toContain("tempestVitest()");
+        expect(rows[0][2]).toContain('Unknown file extension ".css"');
+    });
+
+    it("warns on a plain vitest.config without the plugin", () => {
+        const rows = check({
+            "vitest.config.ts":
+                'import { defineConfig } from "vitest/config";\n' +
+                'export default defineConfig({ test: { environment: "jsdom" } });',
+        });
+        expect(statuses(rows)).toEqual(["warn"]);
+    });
+
+    it("does not count the plugin named only in a comment", () => {
+        const rows = check({
+            "vitest.config.ts":
+                "// TODO: add tempestVitest()\n/* createViteConfig later */\n" +
+                "export default defineConfig({});",
+        });
+        expect(statuses(rows)).toEqual(["warn"]);
+    });
+
+    it("does not trust an import of a vite.config that lacks the plugin too", () => {
+        const rows = check({
+            "vite.config.ts": "export default defineConfig({});",
+            "vitest.config.ts":
+                'import viteConfig from "./vite.config";\n' +
+                "export default mergeConfig(viteConfig, defineConfig({ test: {} }));",
+        });
+        expect(statuses(rows)).toEqual(["warn"]);
+    });
+});
+
+describe("checkVitest — setups that pass", () => {
+    it.each([
+        ["tempestVitest()", "export default defineConfig({ plugins: [tempestVitest()] });"],
+        ["createViteConfig", "export default createViteConfig({ overrides: {} });"],
+        [
+            "inline: true",
+            "export default defineConfig({ test: { server: { deps: { inline: true } } } });",
+        ],
+        [
+            "an inline list naming the SDK",
+            'export default defineConfig({ test: { server: { deps: { inline: ["x", "tempest-react-sdk"] } } } });',
+        ],
+    ])("accepts %s", (_, text) => {
+        expect(statuses(check({ "vitest.config.ts": text }))).toEqual(["ok"]);
+    });
+
+    it("accepts a vitest.config merged over a vite.config that uses createViteConfig", () => {
+        const rows = check({
+            "vite.config.ts": "export default createViteConfig();",
+            "vitest.config.ts":
+                'import viteConfig from "./vite.config.ts";\n' +
+                "export default mergeConfig(viteConfig, defineConfig({ test: {} }));",
+        });
+        expect(statuses(rows)).toEqual(["ok"]);
+    });
+
+    it("keeps a URL inside a string from hiding a marker after it", () => {
+        const rows = check({
+            "vitest.config.ts":
+                'const docs = "https://example.com"; export default defineConfig({ plugins: [tempestVitest()] });',
+        });
+        expect(statuses(rows)).toEqual(["ok"]);
+    });
+});

package/bin/lib/fs/contain.mjs

@@ -28,6 +28,13 @@ export function lstatOrNull(path) {
  * not skipped over: its `realpath` throws and the path counts as outside, since
  * `mkdir` or `writeFile` would create whatever the link names.
  *
+ * The answer is about the tree as it is now; nothing makes it and the write that
+ * follows one atomic step. A process swapping a folder for a symlink between the
+ * two can still redirect the write, and Node has no `openat`/`O_NOFOLLOW` walk
+ * to close that. Such a process is already writing inside the user's project, so
+ * it could edit the generated files or `package.json` directly: the window is an
+ * accepted risk, the same one `create-tempest-app` documents (#533).
+ *
  * @param {string} root - Project root.
  * @param {string} path - Absolute path, existing or about to be created.
  * @returns {boolean}

package/bin/lib/openapi/escape.mjs

@@ -16,7 +16,11 @@
  *   {@link assertNoCollision}, never silently merged;
  * - string position → `JSON.stringify` at the call site;
  * - doc comment → {@link commentText};
- * - URL template literal → {@link urlTemplate}.
+ * - URL template literal → {@link urlTemplate};
+ * - the developer's terminal → {@link terminalText}.
+ *
+ * One more check covers the text that becomes a URL rather than being escaped
+ * into one: {@link assertSafePath}.
  */
 
 const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
@@ -150,19 +154,79 @@ export function assertNoCollision(entries, what) {
     }
 }
 
+/**
+ * C0 and C1 control characters except tab and line feed: everything a terminal
+ * may read as the start of an escape sequence (`ESC`, the 8-bit `CSI` and
+ * `OSC`), plus `CR` and backspace, which rewrite what is already on the line.
+ */
+const TERMINAL_CONTROLS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+
+/**
+ * Make spec text safe to print to the developer's terminal.
+ *
+ * `tempest gen api` echoes the spec's tag names, and its errors quote spec
+ * names. `JSON.stringify` escapes the C0 range but leaves the C1 range raw, so
+ * neither path was safe on its own: a tag carrying `ESC ] 0 ; ... BEL` retitled
+ * the terminal window, and an OSC 8 sequence printed a clickable link whose
+ * target the developer never saw (#533). Every control character a terminal
+ * acts on is dropped; tab and line feed are kept so a multi-line error still
+ * reads as one.
+ *
+ * @param {unknown} text - Text that may come from the spec.
+ * @returns {string} The text without terminal control characters.
+ */
+export function terminalText(text) {
+    return String(text).replace(TERMINAL_CONTROLS, "");
+}
+
 /**
  * Make spec text safe inside a `/** ... *\/` block comment.
  *
  * Line terminators collapse to a space, so the text cannot start a new line of
  * the comment, and every `*\/` is broken as `*\\/` so it cannot close it.
+ * Terminal control characters are dropped too ({@link terminalText}): they are
+ * not code, but printing the generated file with `cat` would replay them.
  *
  * @param {unknown} text - The spec text (tag, summary, path).
  * @returns {string} The neutralized single-line text.
  */
 export function commentText(text) {
-    return String(text)
-        .replace(/[\r\n\u2028\u2029]+/g, " ")
-        .replace(/\*\//g, "*\\/");
+    return terminalText(String(text).replace(/[\r\n\u2028\u2029]+/g, " ")).replace(/\*\//g, "*\\/");
+}
+
+/**
+ * Throw when an OpenAPI path key would not stay a path under the client's
+ * `baseURL`.
+ *
+ * The key becomes the URL the generated method requests, and the client passes
+ * an absolute URL through untouched: a key `"https://other.example/x"` made the
+ * method call another origin \u2014 the Bearer is withheld there, but the body and,
+ * with `credentials: "include"`, the cookies were not. A static `.` or `..`
+ * segment (`"/../x"`) climbs out of the `baseURL`'s path prefix once the URL is
+ * normalized. OpenAPI requires a path key to start with `/` and to be relative
+ * to the server URL, so neither is a valid spec; both are refused before any
+ * file is written instead of becoming a call the developer never reads. `\` is
+ * a separator and `%2e` a dot here because the WHATWG URL parser normalizes them
+ * that way.
+ *
+ * @param {unknown} path - The key from `paths`.
+ * @throws {Error} When the key does not start with `/` or has a dot segment.
+ */
+export function assertSafePath(path) {
+    if (typeof path !== "string" || !path.startsWith("/")) {
+        throw new Error(
+            `OpenAPI path ${JSON.stringify(path)} does not start with "/". A path key is relative to the server URL; an absolute URL here would send the request to another origin.`,
+        );
+    }
+    const dotSegment = path
+        .replace(/[?#][\s\S]*$/, "")
+        .split(/[/\\]/)
+        .some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment));
+    if (dotSegment) {
+        throw new Error(
+            `OpenAPI path ${JSON.stringify(path)} has a "." or ".." segment, which leaves the baseURL's path once the URL is normalized. Rename the path in the spec.`,
+        );
+    }
 }
 
 /**