tempest-react-sdk 0.77.0 → 0.79.0

package/README.md

@@ -172,7 +172,7 @@ Everything else (`zod`, `zustand`, `dexie`, `react-hook-form`, `@tanstack/react-
 | `react`, `react-dom` (`^18 \|\| ^19`) | **Peer (required)** | Everything                                                              |
 | `react-router` (`^7 \|\| ^8`)         | **Peer (required)** | `AppRouter`, `defineRoutes`, `RouteGuard`, routing re-exports           |
 | `@tanstack/react-query` (`^5`)        | Direct dep (auto)   | `QueryProvider`, `createQueryKeys`, `AppProviders`                      |
-| `zod` (`^3.23 \|\| ^4`)               | Direct dep (auto)   | `parseResponse`, `validateForm`, `zodResolver`, `useZodForm`            |
+| `zod` (`^4.6.6`)                      | Direct dep (auto)   | `parseResponse`, `validateForm`, `zodResolver`, `useZodForm`            |
 | `zustand` (`^4 \|\| ^5`)              | Direct dep (auto)   | `createAuthStore`, `createStore`, `createSelectors`                     |
 | `dexie` (`^4.4`)                      | Direct dep (auto)   | `createOfflineStore`                                                    |
 | `react-hook-form` (`^7.76`)           | Direct dep (auto)   | `zodResolver`, `useZodForm`, masked inputs                              |
@@ -189,7 +189,7 @@ npm install tempest-react-sdk react react-dom react-router
 
 **Bundle impact**: every bundled dep is externalised in the SDK's Rollup config, and `dist/` ships with the module graph preserved (one file per source module), so your bundler drops what you don't import instead of inheriting one opaque blob — importing `cn` alone costs **153 B** brotli, a full app shell around **6.8 KB**. Your app's bundler (Vite / webpack / Rspack) resolves the deps from `node_modules` and tree-shakes them the same way — if you never call `createOfflineStore`, Dexie never enters your final bundle.
 
-**Version conflicts**: if your app already pins (say) `zod@3.20`, npm dedupes when the range is compatible. If ranges diverge you get two copies — pin a single version in your own `package.json` to force one, or open an issue if the SDK's range is too tight.
+**Version conflicts**: if your app already pins (say) `zod@4.6.6`, npm dedupes when the range is compatible. If ranges diverge you get two copies — pin a single version in your own `package.json` to force one, or open an issue if the SDK's range is too tight.
 
 Adapters for external SDKs (`@sentry/browser`, `posthog-js`, `@growthbook/growthbook`, `launchdarkly-js-client-sdk`) are **not** bundled — install those only when you opt into the adapter. The caller passes the SDK instance to the factory.
 
@@ -273,7 +273,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `auth` _(peer: `zustand`)_                                                                        | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, **passkeys/WebAuthn**: `createPasskeyClient`, `usePasskeyRegistration`, `usePasskeySignIn`, `usePasskeyCapabilities`, `isPasskeySupported`, `isPlatformAuthenticatorAvailable`, `isConditionalMediationAvailable`, `classifyPasskeyError`, `PasskeyError`, `base64UrlToBytes`, `bytesToBase64Url`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `oauth` _(caller injects `@react-oauth/google`)_                                                  | `GoogleSignIn` (normalises Google's credential/error payload), `useOAuthCallback` (runs the callback exchange once, StrictMode-proof), types: `GoogleSignInProps`, `OAuthCredential`, `OAuthError`, `UseOAuthCallbackOptions`, `UseOAuthCallbackResult`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `query` _(peer: `@tanstack/react-query`)_                                                         | `QueryProvider`, `createQueryKeys`, `STALE_TIME`, `CACHE_TIME`, `REFETCH_TIME`, `usePaginatedQuery`, `useCursorQuery`, `useOfflineMutation` (optimistic offline mutation + cache rollback), `upsertById`/`removeById` (optimistic list-cache helpers), `persistQueryClientOffline` (IndexedDB cache persistence for offline reads)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `router` _(dep: `react-router`)_                                                                  | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `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`                                                                                                                                                                                                                                                                  |
@@ -309,7 +309,7 @@ Every module is re-exported from the package root — `import { Button, useDebou
 | `auth` _(peer: `zustand`)_                                                                        | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `oauth` _(caller injects `@react-oauth/google`)_                                                  | `GoogleSignIn` (normalises Google's credential/error payload), `useOAuthCallback` (runs the callback exchange once, StrictMode-proof), types: `GoogleSignInProps`, `OAuthCredential`, `OAuthError`, `UseOAuthCallbackOptions`, `UseOAuthCallbackResult`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `query` _(peer: `@tanstack/react-query`)_                                                         | `QueryProvider`, `createQueryKeys`, `STALE_TIME`, `CACHE_TIME`, `REFETCH_TIME`, `usePaginatedQuery`, `useCursorQuery`, `useOfflineMutation` (optimistic offline mutation + cache rollback), `upsertById`/`removeById` (optimistic list-cache helpers), `persistQueryClientOffline` (IndexedDB cache persistence for offline reads)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `router` _(dep: `react-router`)_                                                                  | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
@@ -647,7 +647,7 @@ Every method throws `ApiError` (`status`, `body`, `url`, `code`) on non-2xx resp
 The HTTP client returns untyped JSON (`unknown`). `parseResponse` validates against a zod schema and gives you a `ZodError`-aware failure message tied to the request.
 
 ```ts
-import { createApiClient, parseResponse } from "tempest-react-sdk";
+import { encodeIdSegment, createApiClient, parseResponse } from "tempest-react-sdk";
 import { z } from "zod";
 
 const userSchema = z.object({
@@ -657,7 +657,7 @@ const userSchema = z.object({
 });
 
 export async function getUser(id: string) {
-  const raw = await api.get<unknown>(`/users/${id}`);
+  const raw = await api.get<unknown>(`/users/${encodeIdSegment(id)}`);
   return parseResponse(userSchema, raw, `GET /users/${id}`);
 }
 ```

package/bin/lib/alias/collect.mjs

@@ -2,6 +2,7 @@
 import { readdirSync, statSync } from "node:fs";
 import { extname, join, resolve } from "node:path";
 
+import { landsInside } from "../fs/contain.mjs";
 import { isInsideBase } from "./specifier.mjs";
 
 const SOURCE_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -40,6 +41,13 @@ function kindOf(path) {
  * the base; a target that is merely *outside* it yields nothing, so
  * `tempest fix e2e` rewrites nothing instead of quietly rewriting `src/`.
  *
+ * A file that resolves outside the project once symlinks are followed is dropped
+ * too: the walk descends into the base with `readdirSync`, which follows a base
+ * that is itself a link (`src -> /elsewhere`), and the codemod would otherwise
+ * rewrite files that are not the project's. Each such file is handed to
+ * `onOutside`, so the caller can say how many it left alone instead of skipping
+ * them in silence.
+ *
  * Results are sorted so the report — and any diff a reviewer reads — is stable
  * across runs and platforms.
  *
@@ -47,15 +55,24 @@ function kindOf(path) {
  * @param {string} params.root - Project root; relative targets resolve against it.
  * @param {string[]} params.targets - Positional paths from the command line.
  * @param {string} params.baseDir - Absolute alias base directory.
+ * @param {(path: string) => void} [params.onOutside] - Called once per file left
+ *   out because it resolves outside the project.
  * @returns {Array<{ path: string, kind: "source" | "style" }>}
  */
-export function collectFiles({ root, targets, baseDir }) {
+export function collectFiles({ root, targets, baseDir, onOutside = () => {} }) {
     const out = new Map();
+    const outside = new Set();
 
     const addFile = (path) => {
-        if (out.has(path) || !isInsideBase(path, baseDir)) return;
+        if (out.has(path) || outside.has(path) || !isInsideBase(path, baseDir)) return;
         const kind = kindOf(path);
-        if (kind) out.set(path, { path, kind });
+        if (!kind) return;
+        if (!landsInside(root, path)) {
+            outside.add(path);
+            onOutside(path);
+            return;
+        }
+        out.set(path, { path, kind });
     };
 
     const walk = (dir) => {

package/bin/lib/alias/index.mjs

@@ -36,6 +36,7 @@ export { describeTypeScript, loadTypeScript, typeScriptUnavailableReason } from
  *   files: Array<{ path: string, changes: Array<{ from: string, to: string, line: number }> }>,
  *   total: number,
  *   errors: Array<{ path: string, message: string }>,
+ *   outside?: number,
  * }}
  */
 export function aliasImports({ root, targets, dryRun = false }) {
@@ -58,7 +59,16 @@ export function aliasImports({ root, targets, dryRun = false }) {
     const errors = [];
     let total = 0;
 
-    for (const { path, kind } of collectFiles({ root, targets, baseDir })) {
+    let outside = 0;
+    const collected = collectFiles({
+        root,
+        targets,
+        baseDir,
+        onOutside: () => {
+            outside += 1;
+        },
+    });
+    for (const { path, kind } of collected) {
         let text;
         try {
             text = readFileSync(path, "utf8");
@@ -90,5 +100,6 @@ export function aliasImports({ root, targets, dryRun = false }) {
         files,
         total,
         errors,
+        outside,
     };
 }

package/bin/lib/alias/index.test.mjs

@@ -136,3 +136,27 @@ describe("aliasImports — degraded projects", () => {
         expect(read("src/pages/admin/Login.tsx")).toBe(before);
     });
 });
+
+describe("aliasImports — files outside the project", () => {
+    let outside;
+
+    beforeEach(() => {
+        outside = mkdtempSync(join(tmpdir(), "tempest-alias-outside-"));
+    });
+
+    afterEach(() => {
+        rmSync(outside, { recursive: true, force: true });
+    });
+
+    it("does not rewrite through an alias base that is a symlink leaving the project", () => {
+        const before = `import { b } from "../b";\nexport const a = b;\n`;
+        mkdirSync(join(outside, "sub"));
+        writeFileSync(join(outside, "b.ts"), "export const b = 1;\n");
+        writeFileSync(join(outside, "sub", "a.ts"), before);
+        rmSync(join(root, "src"), { recursive: true });
+        symlinkSync(outside, join(root, "src"), "dir");
+
+        expect(run()).toMatchObject({ total: 0, files: [], outside: 2 });
+        expect(readFileSync(join(outside, "sub", "a.ts"), "utf8")).toBe(before);
+    });
+});

package/bin/lib/css/analyze.test.mjs

@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
@@ -64,6 +64,26 @@ describe("analyzeCss — collection", () => {
         expect(analysis.stats.files).toBe(1);
     });
 
+    it("skips a sheet reached through a symlink leaving the project, so fix never rewrites it", () => {
+        const outside = mkdtempSync(join(tmpdir(), "tempest-css-outside-"));
+        try {
+            const before = ".a {\n    color: red;\n    color: red;\n}\n";
+            writeFileSync(join(outside, "a.css"), before);
+            symlinkSync(outside, join(root, "src"), "dir");
+
+            const analysis = analyze(["src"]);
+            applyCssFixes({ analysis });
+
+            expect(analysis.stats.files).toBe(0);
+            expect(analysis.skipped[0]).toMatchObject({
+                reason: "resolves outside the project through a symlink",
+            });
+            expect(readFileSync(join(outside, "a.css"), "utf8")).toBe(before);
+        } finally {
+            rmSync(outside, { recursive: true, force: true });
+        }
+    });
+
     it("sorts findings error → warn → info", () => {
         write("src/a.css", ".a {\n    color: ;\n}\n.b {\n    color: red;\n    color: red;\n}\n");
         const severities = analyze().findings.map((f) => f.severity);

package/bin/lib/css/collect.mjs

@@ -4,6 +4,8 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 
+import { landsInside } from "../fs/contain.mjs";
+
 const SKIP_DIRS = new Set([
     "node_modules",
     "dist",
@@ -19,6 +21,9 @@ const SKIP_DIRS = new Set([
     ".cache",
 ]);
 
+/** `skipped` reason for a sheet that resolves outside the project. */
+export const OUTSIDE_PROJECT = "resolves outside the project through a symlink";
+
 /** Above this size a stylesheet is treated as generated, not authored. */
 const MAX_BYTES = 512 * 1024;
 
@@ -35,6 +40,11 @@ export function looksMinified(text) {
 /**
  * Collect the project's own `.css` files.
  *
+ * A sheet that resolves outside the project once symlinks are followed is
+ * skipped with a reason: an explicit target that is a link (`tempest fix src`
+ * with `src -> /elsewhere`) is walked through it, and `fix` would rewrite sheets
+ * that are not the project's.
+ *
  * @param {object} params
  * @param {string} params.root - Project root; relative targets resolve against it.
  * @param {string[]} [params.targets] - Positional paths from the command line.
@@ -62,6 +72,10 @@ export function collectStylesheets({ root, targets = ["."], maxFiles = MAX_FILES
             skipped.push({ path, reason: "larger than 512 KB — treated as generated" });
             return;
         }
+        if (!landsInside(root, path)) {
+            skipped.push({ path, reason: OUTSIDE_PROJECT });
+            return;
+        }
         if (/\.min\.css$/.test(path)) {
             skipped.push({ path, reason: "minified" });
             return;

package/bin/lib/css/extract.mjs

@@ -18,13 +18,17 @@
 //     dead and take the remaining styles down with it;
 //   - the class is only ever read as `styles.row` / `styles["row"]`, never
 //     through a computed key or by handing the whole object around;
-//   - the target global sheet exists AND some source file imports it, because
-//     appending to a stylesheet nobody loads is a silent no-op;
+//   - no declaration carries a line terminator, so the appended rule is the
+//     same lines it was in the module and cannot open a new line of its own;
+//   - the target global sheet is a regular file (not a symlink) whose realpath is
+//     inside the project, AND some source file imports it, because appending to a
+//     stylesheet nobody loads is a silent no-op;
 //   - the new global name collides with nothing already in that sheet.
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 
 import { discoverAlias } from "../alias/discover.mjs";
+import { landsInside, lstatOrNull } from "../fs/contain.mjs";
 import { loadTypeScript, typeScriptUnavailableReason } from "../alias/typescript.mjs";
 import { collectSources, indexClassUses, resolveSpecifier } from "./references.mjs";
 import { parseCss } from "./parse.mjs";
@@ -33,6 +37,9 @@ import { declSignature } from "./semantic.mjs";
 /** A repeated block is only worth extracting from this many declarations up. */
 const MIN_DECLS = 3;
 
+/** CSS newlines (`\n`, `\r`, `\f`) plus the two Unicode line separators. */
+const LINE_TERMINATOR = /[\n\r\f\u2028\u2029]/;
+
 /** Stylesheets treated as "the project's global sheet", in order of preference. */
 const TARGET_CANDIDATES = [
     "src/styles/globals.css",
@@ -82,7 +89,7 @@ export function classNamesIn(parsed) {
  */
 export function findGlobalSheet({ root, explicit, alias }) {
     const candidates = explicit ? [explicit] : TARGET_CANDIDATES;
-    const found = candidates.map((rel) => join(root, rel)).find(existsSync);
+    const found = candidates.map((rel) => join(root, rel)).find((path) => lstatOrNull(path));
     if (!found) {
         return {
             error: explicit
@@ -95,6 +102,9 @@ export function findGlobalSheet({ root, explicit, alias }) {
             error: `${relative(root, found)} é um CSS Module — a folha alvo tem que ser global`,
         };
     }
+    const unsafe = unsafeTargetReason(root, found);
+    if (unsafe) return { error: `${relative(root, found)} ${unsafe} — recusado` };
+    const realFound = realpathSync(found);
 
     const imported = collectSources({ root }).some((file) => {
         let text;
@@ -106,7 +116,7 @@ export function findGlobalSheet({ root, explicit, alias }) {
         if (!text.includes(".css")) return false;
         for (const match of text.matchAll(/["']([^"']+\.css)["']/g)) {
             const target = resolveSpecifier({ specifier: match[1], fromFile: file, alias });
-            if (target === found) return true;
+            if (target !== null && realpathOrNull(target) === realFound) return true;
         }
         return false;
     });
@@ -118,6 +128,47 @@ export function findGlobalSheet({ root, explicit, alias }) {
     return { path: found, file: relative(root, found) };
 }
 
+/**
+ * `realpath` that answers `null` for a missing or dangling path.
+ *
+ * @param {string} path - Absolute path.
+ * @returns {string | null}
+ */
+function realpathOrNull(path) {
+    try {
+        return realpathSync(path);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Why the candidate global sheet must not be appended to, or `null`.
+ *
+ * `writeFileSync` follows symlinks, so a `src/index.css` that is a link — or
+ * that sits under a linked folder pointing out of the project — carries the
+ * append to wherever it points: measured before this check, a link to a shell rc
+ * file got the extracted rule appended, and a custom property value with a
+ * newline in it became a line the shell ran.
+ *
+ * The rule matches the generators': the sheet itself must be a regular file
+ * (`lstat`, so a link — dangling included — is refused), and its `realpath` must
+ * land inside `realpath(root)`. A symlinked folder that stays inside the project
+ * (a monorepo's `src -> app/src`) is accepted — the write lands in the project
+ * either way, and refusing it would switch the pass off for a legitimate layout.
+ *
+ * @param {string} root - Project root.
+ * @param {string} path - Absolute candidate path, which `lstat` sees.
+ * @returns {string | null} A phrase completing "`<file>` …", or `null`.
+ */
+function unsafeTargetReason(root, path) {
+    const stat = lstatOrNull(path);
+    if (stat?.isSymbolicLink()) return "é um symlink, e a escrita seguiria o link";
+    if (!stat?.isFile()) return "não é um arquivo comum";
+    if (!landsInside(root, path)) return "fica fora do projeto depois de resolver symlinks";
+    return null;
+}
+
 /** Group the analysed sheets by identical declaration block. */
 function groupBySignature(sheets) {
     const groups = new Map();
@@ -145,6 +196,13 @@ function occurrenceRefusal({ sheet, block, className, uses, opaqueModules }) {
     }
     if (!className) return `\`${block.prelude}\` não é uma classe simples`;
 
+    const broken = block.decls.find(
+        (d) => LINE_TERMINATOR.test(d.prop) || LINE_TERMINATOR.test(d.value),
+    );
+    if (broken) {
+        return `a declaração \`${broken.prop.split(LINE_TERMINATOR)[0]}\` tem quebra de linha — copiada pra folha global, viraria uma linha nova fora da regra`;
+    }
+
     const mentions = sheet.parsed.blocks.filter(
         (other) =>
             other !== block && new RegExp(`\\.${className}(?![A-Za-z0-9_-])`).test(other.prelude),

package/bin/lib/css/extract.test.mjs

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { analyzeCss } from "./analyze.mjs";
@@ -295,6 +295,20 @@ describe("planExtraction — refusals", () => {
         expect(result.message).toContain("é um CSS Module");
     });
 
+    it("refuses a declaration with a line break instead of copying it into the global sheet", () => {
+        twoCopies();
+        const broken =
+            ".row {\n    --payload: x\necho INJECTED\n;\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n.title {\n    font-weight: 600;\n}\n";
+        write("src/components/Card.module.css", broken);
+        write("src/components/List.module.css", broken.replace(".row", ".line"));
+        const result = plan();
+        expect(result.groups).toEqual([]);
+        expect(result.refusals.map((r) => r.reason)).toEqual([
+            expect.stringContaining("tem quebra de linha"),
+            expect.stringContaining("tem quebra de linha"),
+        ]);
+    });
+
     it("reports a missing TypeScript instead of guessing at the call sites", () => {
         twoCopies();
         rmSync(join(root, "node_modules", "typescript"), { recursive: true, force: true });
@@ -302,3 +316,98 @@ describe("planExtraction — refusals", () => {
         expect(result.status).toBe("no-typescript");
     });
 });
+
+describe("planExtraction — the global sheet stays inside the project (#483)", () => {
+    let outside;
+
+    beforeEach(() => {
+        project();
+        twoCopies();
+        outside = mkdtempSync(join(tmpdir(), "tempest-extract-outside-"));
+    });
+
+    afterEach(() => {
+        rmSync(outside, { recursive: true, force: true });
+    });
+
+    /** Plan and apply, the way `tempest fix --extract-css` does. */
+    const run = () => {
+        const result = plan();
+        applyExtraction({ plan: result });
+        return result;
+    };
+
+    it("refuses a src/index.css that is a symlink to a file outside the project", () => {
+        const victim = join(outside, "victimrc");
+        writeFileSync(victim, "echo ORIGINAL\n");
+        rmSync(join(root, "src/index.css"));
+        symlinkSync(victim, join(root, "src/index.css"));
+
+        const result = run();
+
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("é um symlink");
+        expect(readFileSync(victim, "utf8")).toBe("echo ORIGINAL\n");
+    });
+
+    it("refuses a dangling src/index.css symlink instead of falling through to another sheet", () => {
+        rmSync(join(root, "src/index.css"));
+        symlinkSync(join(outside, "not-yet.css"), join(root, "src/index.css"));
+        write("src/app.css", ":root {}\n");
+        write("src/main.tsx", 'import "./index.css";\nimport "./app.css";\n');
+
+        const result = run();
+
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("src/index.css é um symlink");
+    });
+
+    it("refuses a global sheet under a folder that is a symlink leaving the project", () => {
+        writeFileSync(join(outside, "globals.css"), ":root {}\n");
+        symlinkSync(outside, join(root, "src/styles"));
+        write("src/main.tsx", 'import "./styles/globals.css";\n');
+
+        const result = run();
+
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("fica fora do projeto");
+        expect(readFileSync(join(outside, "globals.css"), "utf8")).toBe(":root {}\n");
+    });
+
+    /**
+     * Reversed on purpose. The first version of #483 refused any symlink on the
+     * path, so a monorepo layout like `src/styles -> theme` switched the pass off
+     * with a `!` and exit 0. The write lands inside the project either way; what
+     * is refused is a link on the sheet itself and a realpath that leaves the
+     * project — the same rule as `gen api`/`gen component`.
+     */
+    it("accepts a symlinked folder that stays inside the project, as the generators do", () => {
+        write("theme/globals.css", ":root {}\n");
+        symlinkSync(join(root, "theme"), join(root, "src/styles"));
+        write("src/main.tsx", 'import "./styles/globals.css";\n');
+
+        const result = run();
+
+        expect(result.status).toBe("ok");
+        expect(result.groups).toHaveLength(1);
+        expect(readFileSync(join(root, "theme/globals.css"), "utf8")).toContain(".u-row {");
+    });
+
+    it("refuses a --css-target outside the project", () => {
+        writeFileSync(join(outside, "x.css"), "");
+        const result = plan({ target: relative(root, join(outside, "x.css")) });
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("fora do projeto");
+    });
+
+    it("matches importers by realpath, so a project under a symlinked path still works", () => {
+        const linked = join(outside, "linked-project");
+        symlinkSync(root, linked);
+        const result = planExtraction({
+            analysis: analyzeCss({ root: linked, targets: ["."], selfDir: SELF_DIR }),
+            root: linked,
+        });
+        expect(result.status).toBe("ok");
+        expect(result.groups).toHaveLength(1);
+    });
+});

package/bin/lib/css/fix.e2e.test.mjs

@@ -188,3 +188,53 @@ describe("tempest fix --extract-css", () => {
         expect(readFileSync(join(root, "src/index.css"), "utf8")).not.toContain(".u-row");
     });
 });
+
+describe("tempest fix — files outside the project are skipped out loud", () => {
+    let outside;
+
+    beforeEach(() => {
+        outside = mkdtempSync(join(tmpdir(), "tempest-fix-outside-"));
+    });
+
+    afterEach(() => {
+        rmSync(outside, { recursive: true, force: true });
+    });
+
+    it("the CSS pass prints how many sheets it skipped", () => {
+        const before = ".a {\n    color: red;\n    color: red;\n}\n";
+        writeFileSync(join(outside, "a.css"), before);
+        symlinkSync(outside, join(root, "src"), "dir");
+
+        const { out } = fix(["src"]);
+
+        expect(out).toContain("! 1 arquivo(s) fora do projeto (symlink) — pulados");
+        expect(readFileSync(join(outside, "a.css"), "utf8")).toBe(before);
+    });
+
+    it("the alias pass prints how many files it skipped", () => {
+        const typescript = dirname(
+            createRequire(import.meta.url).resolve("typescript/package.json"),
+        );
+        mkdirSync(join(root, "node_modules"));
+        symlinkSync(typescript, join(root, "node_modules", "typescript"), "dir");
+        write(
+            "tsconfig.json",
+            JSON.stringify({ compilerOptions: { paths: { "@/*": ["./src/*"] } } }),
+        );
+        const before = 'import { b } from "../b";\nexport const a = b;\n';
+        mkdirSync(join(outside, "sub"));
+        writeFileSync(join(outside, "b.ts"), "export const b = 1;\n");
+        writeFileSync(join(outside, "sub", "a.ts"), before);
+        symlinkSync(outside, join(root, "src"), "dir");
+
+        const result = spawnSync(process.execPath, [CLI, "fix", "--no-css"], {
+            cwd: root,
+            encoding: "utf8",
+            env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+        });
+        const out = `${result.stdout}${result.stderr}`;
+
+        expect(out).toContain("! 2 arquivo(s) fora do projeto (symlink) — pulados");
+        expect(readFileSync(join(outside, "sub", "a.ts"), "utf8")).toBe(before);
+    });
+});

package/bin/lib/css/index.mjs

@@ -1,6 +1,11 @@
 // Public surface of the CSS analysis used by `tempest doctor` and `tempest fix`.
 export { analyzeCss, applyCssFixes } from "./analyze.mjs";
-export { collectStylesheets, customPropertiesInSources, looksMinified } from "./collect.mjs";
+export {
+    collectStylesheets,
+    customPropertiesInSources,
+    looksMinified,
+    OUTSIDE_PROJECT,
+} from "./collect.mjs";
 export { countBySeverity, finding, SEVERITY, sortFindings } from "./findings.mjs";
 export { fixCss } from "./fix.mjs";
 export {

package/bin/lib/fs/contain.mjs

@@ -0,0 +1,50 @@
+// Where a CLI write really lands. Every pass that writes into the user's project
+// (`gen *`, `fix`'s alias and CSS passes) asks these before touching a path, so a
+// symlink planted in a cloned repository cannot carry a write out of it.
+import { lstatSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, sep } from "node:path";
+
+/**
+ * `lstat` that answers `null` for a missing path instead of throwing.
+ *
+ * @param {string} path - Absolute path.
+ * @returns {import("node:fs").Stats | null}
+ */
+export function lstatOrNull(path) {
+    try {
+        return lstatSync(path);
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Whether `path` lands inside `root` once symlinks are resolved.
+ *
+ * Resolves the nearest ancestor that exists through `realpath`, so `../x`, an
+ * absolute path and an ancestor that is a symlink to somewhere else
+ * (`src/components -> /elsewhere`) are all seen where they really land. The walk
+ * stops at the nearest ancestor `lstat` sees, so a dangling symlink on the way is
+ * not skipped over: its `realpath` throws and the path counts as outside, since
+ * `mkdir` or `writeFile` would create whatever the link names.
+ *
+ * @param {string} root - Project root.
+ * @param {string} path - Absolute path, existing or about to be created.
+ * @returns {boolean}
+ */
+export function landsInside(root, path) {
+    let existing = path;
+    while (lstatOrNull(existing) === null && dirname(existing) !== existing) {
+        existing = dirname(existing);
+    }
+    let real;
+    let realRoot;
+    try {
+        real = realpathSync(existing);
+        realRoot = realpathSync(root);
+    } catch {
+        return false;
+    }
+    const rel = relative(realRoot, real);
+    return !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel));
+}