.

Author: kantord

docs/mocks.md

@@ -1,17 +1,17 @@
 MSW Auto-Mocker
 
-- Handlers: `src/mocks/handlers.ts` combines custom and auto-generated.
-- Custom: add overrides in `src/mocks/customHandlers/index.ts`.
-- Auto-gen: `src/mocks/mocker.ts` reads `swagger.json` and creates fixtures in `src/mocks/fixtures` on first run.
+- Handlers: `src/mocks/handlers.ts` combines non-schema mocks and auto-generated mocks.
+- Non-schema mocks: add hand-written handlers in `src/mocks/customHandlers/index.ts`. These run before auto-generated handlers so they can replace or extend behavior when needed.
+- Auto-generated: `src/mocks/mocker.ts` reads `swagger.json` and creates fixtures under `src/mocks/fixtures` on first run.
 - Validation: Loaded fixtures are validated with Ajv; errors log to console.
 
 Usage
-- Vitest: already wired via `src/mocks/test.setup.ts`. Run `pnpm test`.
-- Browser dev (optional): import and call `startWorker()` from `src/mocks/browser.ts` in your app's dev entry.
-- Standalone server (dev): run `pnpm mock:server` to start an HTTP mock server on `http://localhost:9090` (configurable via `MOCK_PORT`). Point your app's API base URL or a Next.js rewrite to this server to consume mock data without a real backend.
+- Vitest: tests initialize MSW in `src/mocks/test.setup.ts`. Run `pnpm test`.
+- Browser (optional): call `startWorker()` from `src/mocks/browser.ts` in your development entry point to mock requests in the browser.
+- Standalone server (dev): `pnpm mock:server` starts an HTTP mock server at `http://localhost:9090` (configurable with `MOCK_PORT`). Point API requests or Next.js rewrites to this origin to develop without a live backend.
 
 Regeneration
-- Delete a fixture file or run with `AUTO_MOCKER_FORCE=1` to re-generate.
+- Delete a fixture file to re-generate it on next request.
 
 Failure behavior (always strict)
 - If a schema is missing or faker fails, the handler responds 500 and does not write a placeholder.

src/mocks/customHandlers/index.ts

@@ -1,7 +1,8 @@
 import type { RequestHandler } from "msw";
 
-// Add hand-written handlers here. These take precedence over
-// auto-generated ones because they are spread first in handlers.ts.
+// Add non-schema, hand-written mocks here.
+// These are composed before the auto-generated handlers (handlers.ts),
+// so they can replace or extend behavior where needed.
 export const customHandlers: RequestHandler[] = [
   // Example override: customize one endpoint's payload
   // http.get("*/registry/v0.1/servers", () =>

src/mocks/fixtures/README.md

@@ -5,8 +5,8 @@ Fixtures are auto-generated on first run by the MSW Auto-Mocker.
 - You can edit these files to tailor responses for tests or local dev.
 
 Notes
-- Custom handlers in `src/mocks/customHandlers` run before auto-generated ones.
-- To force re-generate a fixture, delete it or set env `AUTO_MOCKER_FORCE=1`.
+- Non-schema mocks in `src/mocks/customHandlers` run before auto-generated ones.
+- To re-generate a fixture, delete the file; it will be recreated on next request.
 - If your project exposes OpenAPI response types via `@api/types.gen`, you can
   enable type enforcement by setting `USE_TYPES_FOR_FIXTURES = true` in
   `src/mocks/mocker.ts`.

src/mocks/mocker.ts

@@ -17,9 +17,6 @@ const USE_TYPES_FOR_FIXTURES = false; // set true if you have @api/types.gen ali
 // Strip these noisy prefixes from generated fixture folder names.
 const PREFIXES_TO_STRIP = ["api_v1beta_", "api_v0_"];
 
-// Allow forcing regeneration of fixtures via env flag.
-const FORCE_REGENERATE = process.env.AUTO_MOCKER_FORCE === "1";
-
 // ===== Runtime setup =====
 // Resolve module directory
 const __filename = fileURLToPath(import.meta.url);
@@ -420,7 +417,7 @@ export function autoGenerateHandlers() {
           }
 
           const hasFile = fs.existsSync(fixtureFileName);
-          if ((FORCE_REGENERATE || !hasFile) && successStatus !== "204") {
+          if (!hasFile && successStatus !== "204") {
             let payload: unknown;
             if (successStatus) {
               const schema = getJsonSchemaFromOperation(