@warlock.js/core 5.30.0 → 5.31.0

package/esm/generations/features/web.feature.mjs

@@ -1,12 +1,12 @@
 import { rootPath, srcPath } from "../../utils/paths.mjs";
 import "../../utils/index.mjs";
+import { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "../generation-fs.mjs";
 import { webContactControllerStub, webContactRoutesStub, webHomePageStub, webHomeRegisterStub, webRootStub } from "../stubs.mjs";
 import { INSTALLED_WARLOCK_VERSION } from "./types.mjs";
 import { insertConnectorEntry } from "./shared/insert-connector-entry.mjs";
 import { relocateConflictingHomeRoute } from "./shared/relocate-conflicting-home-route.mjs";
 import { resolveContactScaffold } from "./shared/resolve-contact-scaffold.mjs";
 import { colors } from "@mongez/copper";
-import { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "@warlock.js/fs";
 
 //#region ../../packages/core/src/generations/features/web.feature.ts
 /** The one vite range shared by every feature (web's peer range is `>=7.3.5 <8`). */

package/esm/generations/features/web.feature.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"web.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/web.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from \"@warlock.js/fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport { insertConnectorEntry } from \"./shared/insert-connector-entry\";\nimport { relocateConflictingHomeRoute } from \"./shared/relocate-conflicting-home-route\";\nimport { resolveContactScaffold } from \"./shared/resolve-contact-scaffold\";\nimport {\n  webContactControllerStub,\n  webContactRoutesStub,\n  webHomePageStub,\n  webHomeRegisterStub,\n  webRootStub,\n} from \"../stubs\";\nimport { type FeatureDefinition, INSTALLED_WARLOCK_VERSION } from \"./types\";\n\n/** The one vite range shared by every feature (web's peer range is `>=7.3.5 <8`). */\nexport const VITE_RANGE = \"^7.3.5\";\n\n/**\n * Register the WebConnector in `warlock.config.ts`, and ONLY there.\n *\n * It belongs to the config array or to app code, never both. Both halves are\n * registered before app code loads — the CLI preloader in dev, the generated\n * entry in production — so also calling `connectorsManager.register(...)` in\n * `src/app/main.ts` boots the connector twice and installs every page route\n * twice. That surfaces at PRODUCTION boot as `Route name \"...\" is already\n * taken`, because pages and API routes share one route-name namespace.\n *\n * The config array is the half to prefer: `warlock build` reads the same array\n * to drain each connector's build contribution, so \"built for\" and \"boots with\"\n * cannot drift.\n *\n * String surgery rather than a TypeScript parse: `warlock.config.ts` is an\n * app-owned file that may carry any formatting, and a parse-and-print would\n * reformat the parts we did not come to change.\n */\nasync function registerWebConnector(): Promise<void> {\n  const configPath = rootPath(\"warlock.config.ts\");\n\n  if (!(await fileExistsAsync(configPath))) {\n    console.log(\n      `${colors.yellowBright(\"warlock.config.ts\")} not found — add this yourself:\\n` +\n        `  import { webConnector } from \"@warlock.js/web/connector\";\\n` +\n        `  export default defineConfig({ connectors: [webConnector()] });`,\n    );\n\n    return;\n  }\n\n  const current = await getFileAsync(configPath);\n\n  if (current.includes(\"webConnector\")) {\n    console.log(`${colors.yellowBright(\"webConnector\")} already registered, skipping...`);\n\n    return;\n  }\n\n  const importLine = 'import { webConnector } from \"@warlock.js/web/connector\";';\n  let next = current.includes(importLine) ? current : `${importLine}\\n${current}`;\n\n  // An existing `connectors: [` gains one entry; otherwise the key is added to\n  // the object `defineConfig` receives.\n  const insertion = insertConnectorEntry(next, \"webConnector()\");\n\n  if (insertion.status === \"already-present\") {\n    return;\n  }\n\n  if (insertion.status === \"added\") {\n    next = insertion.next;\n  } else if (next.includes(\"defineConfig({\")) {\n    next = next.replace(\"defineConfig({\", \"defineConfig({\\n  connectors: [webConnector()],\");\n  } else {\n    console.log(\n      `${colors.yellowBright(\"warlock.config.ts\")} has no recognisable defineConfig({...}) — ` +\n        \"add `connectors: [webConnector()]` yourself.\",\n    );\n\n    return;\n  }\n\n  await putFileAsync(configPath, next);\n  console.log(`${colors.green(\"✓\")} Registered webConnector in warlock.config.ts`);\n}\n\n/**\n * Scaffold the smallest page layer that renders, and register the connector.\n *\n * `src/web/root.tsx` is the sentinel for \"already scaffolded\" — the framework\n * ships a default root, so its presence means a human has been here.\n */\nasync function completeWebInstallation(_options: CommandActionData) {\n  const rootFile = srcPath(\"web/root.tsx\");\n\n  if (await fileExistsAsync(rootFile)) {\n    console.log(`${colors.yellowBright(\"src/web\")} already scaffolded, skipping...`);\n  } else {\n    await ensureDirectoryAsync(srcPath(\"web\"));\n    await putFileAsync(rootFile, webRootStub);\n    console.log(`${colors.green(\"✓\")} Created src/web/root.tsx`);\n\n    const collision = await relocateConflictingHomeRoute();\n\n    if (collision.outcome === \"relocated\") {\n      console.log(\n        `${colors.green(\"✓\")} Moved the existing ${colors.yellowBright('GET \"/\"')} route to ` +\n          `${colors.yellowBright('\"/welcome\"')} in ${colors.yellowBright(`src/${collision.relativePath}`)} — ` +\n          \"the new page owns `/` now, and the JSON welcome route still answers at /welcome.\",\n      );\n    }\n\n    // The page is written ONLY when `/` is provably free. Writing it while\n    // another handler holds `/` produces a homepage that 500s on first request,\n    // which is precisely the outcome a scaffolder must never hand back.\n    if (collision.outcome === \"conflict\" || collision.outcome === \"failed\") {\n      const verb =\n        collision.outcome === \"failed\" ? colors.redBright(\"✗\") : colors.yellowBright(\"!\");\n\n      console.log(\n        `${verb} Did not create src/web/index.page.tsx: ${collision.reason}.\\n` +\n          `  The page stub declares ${colors.yellowBright('route.path = \"/\"')}, and two handlers on one ` +\n          \"path is a 500 at request time, not a startup error.\\n\" +\n          `  Free up ${colors.yellowBright('GET \"/\"')} under src/app — move it to a path of its own, ` +\n          \"or remove it — then create src/web/index.page.tsx yourself. Giving the page a `route` other \" +\n          \"than `/` works too.\",\n      );\n\n      // Non-zero on BOTH branches. The page layer this command exists to\n      // scaffold was not scaffolded, and a 0 here is the exact \"looked like it\n      // worked\" signal that put `/` in this state to begin with — a conflict we\n      // declined to guess at is still an incomplete install, not a success.\n      //\n      // `exitCode` rather than `exit(1)`: the connector below still has to be\n      // registered, and any other feature in the same `warlock add` invocation\n      // still has to install, or the project is left half-wired on top of this.\n      process.exitCode = 1;\n    } else {\n      await putFileAsync(srcPath(\"web/index.page.tsx\"), webHomePageStub);\n      await putFileAsync(srcPath(\"web/index.register.ts\"), webHomeRegisterStub);\n\n      // Unlike root.tsx above, the contact controller and its routes file are\n      // ordinary application files a project can already have — independently\n      // of ever having run `warlock add web`. Each is guarded on its OWN\n      // existence, not on the (already-consumed) root.tsx sentinel, so an\n      // existing `contact` module is skipped rather than clobbered. See\n      // resolveContactScaffold's doc comment for why.\n      const contactPlan = resolveContactScaffold({\n        controllerExists: await fileExistsAsync(\n          srcPath(\"app/contact/controllers/contact.controller.ts\"),\n        ),\n        routesExists: await fileExistsAsync(srcPath(\"app/contact/routes.ts\")),\n      });\n\n      if (contactPlan.writeController) {\n        await ensureDirectoryAsync(srcPath(\"app/contact/controllers\"));\n        await putFileAsync(\n          srcPath(\"app/contact/controllers/contact.controller.ts\"),\n          webContactControllerStub,\n        );\n      }\n\n      if (contactPlan.writeRoutes) {\n        await ensureDirectoryAsync(srcPath(\"app/contact\"));\n        await putFileAsync(srcPath(\"app/contact/routes.ts\"), webContactRoutesStub);\n      }\n\n      console.log(`${colors.green(\"✓\")} Created src/web/index.page.tsx`);\n\n      for (const message of contactPlan.messages) {\n        console.log(message);\n      }\n    }\n  }\n\n  await registerWebConnector();\n}\n\nexport const webFeature: FeatureDefinition = {\n  description:\n    \"Installs @warlock.js/web — SSR React pages served by the Warlock HTTP server. Scaffolds src/web (root.tsx + a home page) and registers the WebConnector in warlock.config.ts. Pages are opt-in: a Warlock app is an API until you add this.\",\n  dependencies: {\n    \"@warlock.js/web\": INSTALLED_WARLOCK_VERSION,\n    \"@mongez/http\": \"^3.5.0\",\n    \"@mongez/react-form\": \"^4.0.0\",\n    \"@mongez/react-localization\": \"^3.4.7\",\n    react: \"^19.2.3\",\n    \"react-dom\": \"^19.2.3\",\n  },\n  devDependencies: {\n    \"@types/react\": \"^19.2.7\",\n    \"@types/react-dom\": \"^19.2.3\",\n    // Loaded through `await import()` by the dev server only, so both are\n    // optional peers of `web` rather than hard dependencies.\n    vite: VITE_RANGE,\n    \"@vitejs/plugin-react\": \"^5.2.0\",\n  },\n  onExecuting: completeWebInstallation,\n};\n"],"mappings":"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"}
+{"version":3,"file":"web.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/web.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport {\n  ensureDirectoryAsync,\n  fileExistsAsync,\n  getFileAsync,\n  putFileAsync,\n} from \"../generation-fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport { insertConnectorEntry } from \"./shared/insert-connector-entry\";\nimport { relocateConflictingHomeRoute } from \"./shared/relocate-conflicting-home-route\";\nimport { resolveContactScaffold } from \"./shared/resolve-contact-scaffold\";\nimport {\n  webContactControllerStub,\n  webContactRoutesStub,\n  webHomePageStub,\n  webHomeRegisterStub,\n  webRootStub,\n} from \"../stubs\";\nimport { type FeatureDefinition, INSTALLED_WARLOCK_VERSION } from \"./types\";\n\n/** The one vite range shared by every feature (web's peer range is `>=7.3.5 <8`). */\nexport const VITE_RANGE = \"^7.3.5\";\n\n/**\n * Register the WebConnector in `warlock.config.ts`, and ONLY there.\n *\n * It belongs to the config array or to app code, never both. Both halves are\n * registered before app code loads — the CLI preloader in dev, the generated\n * entry in production — so also calling `connectorsManager.register(...)` in\n * `src/app/main.ts` boots the connector twice and installs every page route\n * twice. That surfaces at PRODUCTION boot as `Route name \"...\" is already\n * taken`, because pages and API routes share one route-name namespace.\n *\n * The config array is the half to prefer: `warlock build` reads the same array\n * to drain each connector's build contribution, so \"built for\" and \"boots with\"\n * cannot drift.\n *\n * String surgery rather than a TypeScript parse: `warlock.config.ts` is an\n * app-owned file that may carry any formatting, and a parse-and-print would\n * reformat the parts we did not come to change.\n */\nasync function registerWebConnector(): Promise<void> {\n  const configPath = rootPath(\"warlock.config.ts\");\n\n  if (!(await fileExistsAsync(configPath))) {\n    console.log(\n      `${colors.yellowBright(\"warlock.config.ts\")} not found — add this yourself:\\n` +\n        `  import { webConnector } from \"@warlock.js/web/connector\";\\n` +\n        `  export default defineConfig({ connectors: [webConnector()] });`,\n    );\n\n    return;\n  }\n\n  const current = await getFileAsync(configPath);\n\n  if (current.includes(\"webConnector\")) {\n    console.log(`${colors.yellowBright(\"webConnector\")} already registered, skipping...`);\n\n    return;\n  }\n\n  const importLine = 'import { webConnector } from \"@warlock.js/web/connector\";';\n  let next = current.includes(importLine) ? current : `${importLine}\\n${current}`;\n\n  // An existing `connectors: [` gains one entry; otherwise the key is added to\n  // the object `defineConfig` receives.\n  const insertion = insertConnectorEntry(next, \"webConnector()\");\n\n  if (insertion.status === \"already-present\") {\n    return;\n  }\n\n  if (insertion.status === \"added\") {\n    next = insertion.next;\n  } else if (next.includes(\"defineConfig({\")) {\n    next = next.replace(\"defineConfig({\", \"defineConfig({\\n  connectors: [webConnector()],\");\n  } else {\n    console.log(\n      `${colors.yellowBright(\"warlock.config.ts\")} has no recognisable defineConfig({...}) — ` +\n        \"add `connectors: [webConnector()]` yourself.\",\n    );\n\n    return;\n  }\n\n  await putFileAsync(configPath, next);\n  console.log(`${colors.green(\"✓\")} Registered webConnector in warlock.config.ts`);\n}\n\n/**\n * Scaffold the smallest page layer that renders, and register the connector.\n *\n * `src/web/root.tsx` is the sentinel for \"already scaffolded\" — the framework\n * ships a default root, so its presence means a human has been here.\n */\nasync function completeWebInstallation(_options: CommandActionData) {\n  const rootFile = srcPath(\"web/root.tsx\");\n\n  if (await fileExistsAsync(rootFile)) {\n    console.log(`${colors.yellowBright(\"src/web\")} already scaffolded, skipping...`);\n  } else {\n    await ensureDirectoryAsync(srcPath(\"web\"));\n    await putFileAsync(rootFile, webRootStub);\n    console.log(`${colors.green(\"✓\")} Created src/web/root.tsx`);\n\n    const collision = await relocateConflictingHomeRoute();\n\n    if (collision.outcome === \"relocated\") {\n      console.log(\n        `${colors.green(\"✓\")} Moved the existing ${colors.yellowBright('GET \"/\"')} route to ` +\n          `${colors.yellowBright('\"/welcome\"')} in ${colors.yellowBright(`src/${collision.relativePath}`)} — ` +\n          \"the new page owns `/` now, and the JSON welcome route still answers at /welcome.\",\n      );\n    }\n\n    // The page is written ONLY when `/` is provably free. Writing it while\n    // another handler holds `/` produces a homepage that 500s on first request,\n    // which is precisely the outcome a scaffolder must never hand back.\n    if (collision.outcome === \"conflict\" || collision.outcome === \"failed\") {\n      const verb =\n        collision.outcome === \"failed\" ? colors.redBright(\"✗\") : colors.yellowBright(\"!\");\n\n      console.log(\n        `${verb} Did not create src/web/index.page.tsx: ${collision.reason}.\\n` +\n          `  The page stub declares ${colors.yellowBright('route.path = \"/\"')}, and two handlers on one ` +\n          \"path is a 500 at request time, not a startup error.\\n\" +\n          `  Free up ${colors.yellowBright('GET \"/\"')} under src/app — move it to a path of its own, ` +\n          \"or remove it — then create src/web/index.page.tsx yourself. Giving the page a `route` other \" +\n          \"than `/` works too.\",\n      );\n\n      // Non-zero on BOTH branches. The page layer this command exists to\n      // scaffold was not scaffolded, and a 0 here is the exact \"looked like it\n      // worked\" signal that put `/` in this state to begin with — a conflict we\n      // declined to guess at is still an incomplete install, not a success.\n      //\n      // `exitCode` rather than `exit(1)`: the connector below still has to be\n      // registered, and any other feature in the same `warlock add` invocation\n      // still has to install, or the project is left half-wired on top of this.\n      process.exitCode = 1;\n    } else {\n      await putFileAsync(srcPath(\"web/index.page.tsx\"), webHomePageStub);\n      await putFileAsync(srcPath(\"web/index.register.ts\"), webHomeRegisterStub);\n\n      // Unlike root.tsx above, the contact controller and its routes file are\n      // ordinary application files a project can already have — independently\n      // of ever having run `warlock add web`. Each is guarded on its OWN\n      // existence, not on the (already-consumed) root.tsx sentinel, so an\n      // existing `contact` module is skipped rather than clobbered. See\n      // resolveContactScaffold's doc comment for why.\n      const contactPlan = resolveContactScaffold({\n        controllerExists: await fileExistsAsync(\n          srcPath(\"app/contact/controllers/contact.controller.ts\"),\n        ),\n        routesExists: await fileExistsAsync(srcPath(\"app/contact/routes.ts\")),\n      });\n\n      if (contactPlan.writeController) {\n        await ensureDirectoryAsync(srcPath(\"app/contact/controllers\"));\n        await putFileAsync(\n          srcPath(\"app/contact/controllers/contact.controller.ts\"),\n          webContactControllerStub,\n        );\n      }\n\n      if (contactPlan.writeRoutes) {\n        await ensureDirectoryAsync(srcPath(\"app/contact\"));\n        await putFileAsync(srcPath(\"app/contact/routes.ts\"), webContactRoutesStub);\n      }\n\n      console.log(`${colors.green(\"✓\")} Created src/web/index.page.tsx`);\n\n      for (const message of contactPlan.messages) {\n        console.log(message);\n      }\n    }\n  }\n\n  await registerWebConnector();\n}\n\nexport const webFeature: FeatureDefinition = {\n  description:\n    \"Installs @warlock.js/web — SSR React pages served by the Warlock HTTP server. Scaffolds src/web (root.tsx + a home page) and registers the WebConnector in warlock.config.ts. Pages are opt-in: a Warlock app is an API until you add this.\",\n  dependencies: {\n    \"@warlock.js/web\": INSTALLED_WARLOCK_VERSION,\n    \"@mongez/http\": \"^3.5.0\",\n    \"@mongez/react-form\": \"^4.0.0\",\n    \"@mongez/react-localization\": \"^3.4.7\",\n    react: \"^19.2.3\",\n    \"react-dom\": \"^19.2.3\",\n  },\n  devDependencies: {\n    \"@types/react\": \"^19.2.7\",\n    \"@types/react-dom\": \"^19.2.3\",\n    // Loaded through `await import()` by the dev server only, so both are\n    // optional peers of `web` rather than hard dependencies.\n    vite: VITE_RANGE,\n    \"@vitejs/plugin-react\": \"^5.2.0\",\n  },\n  onExecuting: completeWebInstallation,\n};\n"],"mappings":"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"}

package/esm/generations/generation-fs.mjs

@@ -0,0 +1,73 @@
+import { currentGenerationRun, hasPendingContentUnder, pendingGeneratedContent, recordGeneratedFile, recordSkippedFile, setPendingGeneratedContent } from "./generation-run.mjs";
+import * as fs from "@warlock.js/fs";
+
+//#region ../../packages/core/src/generations/generation-fs.ts
+/**
+* The filesystem generation commands write through.
+*
+* Same signatures as the `@warlock.js/fs` functions they wrap, so a feature
+* hook or generator only changes its import. Outside a generation run they
+* pass straight through. Inside one (see `generation-run.ts`) every write is
+* recorded for the `--json` report, and in a `--dry-run` nothing reaches the
+* disk: writes land in an in-memory overlay that later reads in the same run
+* see, so a hook that writes a file and then edits it previews correctly.
+*/
+/** Whether `target` exists on disk or in the dry-run overlay. */
+async function fileExistsAsync$1(target) {
+	if (pendingGeneratedContent(target) !== void 0) return true;
+	return fs.fileExistsAsync(target);
+}
+/** Whether `directory` exists on disk or holds a file in the dry-run overlay. */
+async function directoryExistsAsync$1(directory) {
+	if (hasPendingContentUnder(directory)) return true;
+	return fs.directoryExistsAsync(directory);
+}
+/** Read `target`, preferring what this dry run already "wrote". */
+async function getFileAsync$1(target) {
+	const pending = pendingGeneratedContent(target);
+	if (pending !== void 0) return pending;
+	return fs.getFileAsync(target);
+}
+async function getJsonFileAsync$1(target) {
+	const pending = pendingGeneratedContent(target);
+	if (pending !== void 0) return JSON.parse(pending);
+	return fs.getJsonFileAsync(target);
+}
+/**
+* Write `content` to `target`, recording `create`, `update` or `unchanged`.
+* Identical content is not rewritten.
+*/
+async function putFileAsync$1(target, content) {
+	const run = currentGenerationRun();
+	if (!run) {
+		await fs.putFileAsync(target, content);
+		return;
+	}
+	const exists = await fileExistsAsync$1(target);
+	if (exists && await getFileAsync$1(target) === content) {
+		recordGeneratedFile(target, "unchanged");
+		return;
+	}
+	recordGeneratedFile(target, exists ? "update" : "create");
+	if (run.dryRun) {
+		setPendingGeneratedContent(target, content);
+		return;
+	}
+	await fs.putFileAsync(target, content);
+}
+async function putJsonFileAsync$1(target, value) {
+	if (!currentGenerationRun()) {
+		await fs.putJsonFileAsync(target, value);
+		return;
+	}
+	await putFileAsync$1(target, JSON.stringify(value, null, 2));
+}
+/** Create `directory`; a dry run leaves no empty folders behind. */
+async function ensureDirectoryAsync$1(directory) {
+	if (currentGenerationRun()?.dryRun) return;
+	await fs.ensureDirectoryAsync(directory);
+}
+
+//#endregion
+export { directoryExistsAsync$1 as directoryExistsAsync, ensureDirectoryAsync$1 as ensureDirectoryAsync, fileExistsAsync$1 as fileExistsAsync, getFileAsync$1 as getFileAsync, getJsonFileAsync$1 as getJsonFileAsync, putFileAsync$1 as putFileAsync, putJsonFileAsync$1 as putJsonFileAsync };
+//# sourceMappingURL=generation-fs.mjs.map

package/esm/generations/generation-fs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-fs.mjs","names":["fileExistsAsync","directoryExistsAsync","getFileAsync","getJsonFileAsync","putFileAsync","putJsonFileAsync","ensureDirectoryAsync"],"sources":["../../../../../../../../packages/core/src/generations/generation-fs.ts"],"sourcesContent":["/**\n * The filesystem generation commands write through.\n *\n * Same signatures as the `@warlock.js/fs` functions they wrap, so a feature\n * hook or generator only changes its import. Outside a generation run they\n * pass straight through. Inside one (see `generation-run.ts`) every write is\n * recorded for the `--json` report, and in a `--dry-run` nothing reaches the\n * disk: writes land in an in-memory overlay that later reads in the same run\n * see, so a hook that writes a file and then edits it previews correctly.\n */\nimport * as fs from \"@warlock.js/fs\";\nimport {\n  currentGenerationRun,\n  hasPendingContentUnder,\n  pendingGeneratedContent,\n  recordGeneratedFile,\n  recordSkippedFile,\n  setPendingGeneratedContent,\n} from \"./generation-run\";\n\nexport { recordSkippedFile };\n\n/** Whether `target` exists on disk or in the dry-run overlay. */\nexport async function fileExistsAsync(target: string): Promise<boolean> {\n  if (pendingGeneratedContent(target) !== undefined) return true;\n\n  return fs.fileExistsAsync(target);\n}\n\n/** Whether `directory` exists on disk or holds a file in the dry-run overlay. */\nexport async function directoryExistsAsync(directory: string): Promise<boolean> {\n  if (hasPendingContentUnder(directory)) return true;\n\n  return fs.directoryExistsAsync(directory);\n}\n\n/** Read `target`, preferring what this dry run already \"wrote\". */\nexport async function getFileAsync(target: string): Promise<string> {\n  const pending = pendingGeneratedContent(target);\n\n  if (pending !== undefined) return pending;\n\n  return fs.getFileAsync(target);\n}\n\nexport async function getJsonFileAsync<T = unknown>(target: string): Promise<T> {\n  const pending = pendingGeneratedContent(target);\n\n  if (pending !== undefined) return JSON.parse(pending) as T;\n\n  return fs.getJsonFileAsync<T>(target);\n}\n\n/**\n * Write `content` to `target`, recording `create`, `update` or `unchanged`.\n * Identical content is not rewritten.\n */\nexport async function putFileAsync(target: string, content: string): Promise<void> {\n  const run = currentGenerationRun();\n\n  if (!run) {\n    await fs.putFileAsync(target, content);\n    return;\n  }\n\n  const exists = await fileExistsAsync(target);\n\n  if (exists && (await getFileAsync(target)) === content) {\n    recordGeneratedFile(target, \"unchanged\");\n    return;\n  }\n\n  recordGeneratedFile(target, exists ? \"update\" : \"create\");\n\n  if (run.dryRun) {\n    setPendingGeneratedContent(target, content);\n    return;\n  }\n\n  await fs.putFileAsync(target, content);\n}\n\nexport async function putJsonFileAsync(target: string, value: unknown): Promise<void> {\n  if (!currentGenerationRun()) {\n    await fs.putJsonFileAsync(target, value);\n    return;\n  }\n\n  await putFileAsync(target, JSON.stringify(value, null, 2));\n}\n\n/** Create `directory`; a dry run leaves no empty folders behind. */\nexport async function ensureDirectoryAsync(directory: string): Promise<void> {\n  if (currentGenerationRun()?.dryRun) return;\n\n  await fs.ensureDirectoryAsync(directory);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAuBA,eAAsBA,kBAAgB,QAAkC;CACtE,IAAI,wBAAwB,MAAM,MAAM,QAAW,OAAO;CAE1D,OAAO,GAAG,gBAAgB,MAAM;AAClC;;AAGA,eAAsBC,uBAAqB,WAAqC;CAC9E,IAAI,uBAAuB,SAAS,GAAG,OAAO;CAE9C,OAAO,GAAG,qBAAqB,SAAS;AAC1C;;AAGA,eAAsBC,eAAa,QAAiC;CAClE,MAAM,UAAU,wBAAwB,MAAM;CAE9C,IAAI,YAAY,QAAW,OAAO;CAElC,OAAO,GAAG,aAAa,MAAM;AAC/B;AAEA,eAAsBC,mBAA8B,QAA4B;CAC9E,MAAM,UAAU,wBAAwB,MAAM;CAE9C,IAAI,YAAY,QAAW,OAAO,KAAK,MAAM,OAAO;CAEpD,OAAO,GAAG,iBAAoB,MAAM;AACtC;;;;;AAMA,eAAsBC,eAAa,QAAgB,SAAgC;CACjF,MAAM,MAAM,qBAAqB;CAEjC,IAAI,CAAC,KAAK;EACR,MAAM,GAAG,aAAa,QAAQ,OAAO;EACrC;CACF;CAEA,MAAM,SAAS,MAAMJ,kBAAgB,MAAM;CAE3C,IAAI,UAAW,MAAME,eAAa,MAAM,MAAO,SAAS;EACtD,oBAAoB,QAAQ,WAAW;EACvC;CACF;CAEA,oBAAoB,QAAQ,SAAS,WAAW,QAAQ;CAExD,IAAI,IAAI,QAAQ;EACd,2BAA2B,QAAQ,OAAO;EAC1C;CACF;CAEA,MAAM,GAAG,aAAa,QAAQ,OAAO;AACvC;AAEA,eAAsBG,mBAAiB,QAAgB,OAA+B;CACpF,IAAI,CAAC,qBAAqB,GAAG;EAC3B,MAAM,GAAG,iBAAiB,QAAQ,KAAK;EACvC;CACF;CAEA,MAAMD,eAAa,QAAQ,KAAK,UAAU,OAAO,MAAM,CAAC,CAAC;AAC3D;;AAGA,eAAsBE,uBAAqB,WAAkC;CAC3E,IAAI,qBAAqB,CAAC,EAAE,QAAQ;CAEpC,MAAM,GAAG,qBAAqB,SAAS;AACzC"}

package/esm/generations/generation-run.mjs

@@ -0,0 +1,185 @@
+import path from "node:path";
+import { format, stripVTControlCharacters } from "node:util";
+
+//#region ../../packages/core/src/generations/generation-run.ts
+let activeRun;
+/** Render an absolute path relative to the cwd, `/`-separated, for reports and logs. */
+function toReportPath(target) {
+	return (path.relative(process.cwd(), path.resolve(target)) || target).split(path.sep).join("/");
+}
+/**
+* Start recording a generation command. Every write made through
+* `generation-fs` (and the `generate.*` writer) is recorded until
+* {@link endGenerationRun}; in a dry run nothing reaches the disk.
+*/
+function beginGenerationRun(options) {
+	activeRun = {
+		command: options.command,
+		dryRun: options.dryRun,
+		files: /* @__PURE__ */ new Map(),
+		pending: /* @__PURE__ */ new Map(),
+		details: {},
+		messages: []
+	};
+}
+/** The run being recorded, if any. */
+function currentGenerationRun() {
+	return activeRun;
+}
+/** Whether the current generation command is a dry run. */
+function isGenerationDryRun() {
+	return activeRun?.dryRun === true;
+}
+/**
+* Record what happened to one file. A file first created and later edited in
+* the same run stays `create`: the report describes the run's net effect.
+*/
+function recordGeneratedFile(target, type, reason) {
+	if (!activeRun) return;
+	const key = toReportPath(target);
+	if (activeRun.files.get(key)?.type === "create" && type !== "skip") return;
+	activeRun.files.set(key, reason === void 0 ? {
+		path: key,
+		type
+	} : {
+		path: key,
+		type,
+		reason
+	});
+}
+/** Record a file the command deliberately left alone. */
+function recordSkippedFile(target, reason) {
+	recordGeneratedFile(target, "skip", reason);
+}
+/** Attach a command-specific fact to the report, e.g. `dependencies`. */
+function setGenerationDetail(key, value) {
+	if (!activeRun) return;
+	activeRun.details[key] = value;
+}
+/** The dry-run overlay content for `target`, when this run "wrote" it. */
+function pendingGeneratedContent(target) {
+	return activeRun?.pending.get(path.resolve(target));
+}
+/** Keep `content` as what a dry run would have written to `target`. */
+function setPendingGeneratedContent(target, content) {
+	activeRun?.pending.set(path.resolve(target), content);
+}
+/** Whether any pending dry-run file lives under `directory`. */
+function hasPendingContentUnder(directory) {
+	if (!activeRun) return false;
+	const prefix = path.resolve(directory) + path.sep;
+	for (const file of activeRun.pending.keys()) if (file.startsWith(prefix)) return true;
+	return false;
+}
+/** Stop recording and build the report. */
+function endGenerationRun(result) {
+	const run = activeRun;
+	activeRun = void 0;
+	const files = run ? [...run.files.values()] : [];
+	const report = {
+		schemaVersion: 1,
+		command: run?.command ?? "",
+		dryRun: run?.dryRun ?? false,
+		ok: result.ok,
+		written: files.filter((file) => file.type === "create" || file.type === "overwrite" || file.type === "update").map((file) => file.path),
+		skipped: files.filter((file) => file.type === "skip").map((file) => ({
+			path: file.path,
+			reason: file.reason ?? "exists"
+		})),
+		files,
+		details: run?.details ?? {},
+		messages: run?.messages ?? []
+	};
+	if (result.error !== void 0) report.error = result.error;
+	return report;
+}
+/**
+* Pick the line that explains a failure from what the command printed: the
+* first `Error…` line, else the last line.
+*/
+function failureMessage(messages) {
+	return (messages.find((message) => /^\s*(?:✖\s*)?Error\b/.test(message)) ?? messages[messages.length - 1] ?? "The command failed.").trim();
+}
+/**
+* Run a `make` / `generate.*` / `add` action under the recorder.
+*
+* `--dry-run` writes nothing. `--json` sends everything the command prints
+* to stderr and prints exactly one {@link GenerationReport} on stdout — also
+* when the command fails, including through `process.exit(1)`, so a caller
+* parsing stdout always gets a document.
+*/
+async function runGenerationCommand(command, data, action) {
+	const json = data.options.json === true || data.options.j === true;
+	beginGenerationRun({
+		command,
+		dryRun: data.options.dryRun === true
+	});
+	if (!json) {
+		try {
+			await action(data);
+		} finally {
+			endGenerationRun({ ok: true });
+		}
+		return;
+	}
+	const run = activeRun;
+	const originalLog = console.log;
+	const originalInfo = console.info;
+	const originalWarn = console.warn;
+	const originalError = console.error;
+	let printed = false;
+	const capture = (forward) => (...args) => {
+		run?.messages.push(stripVTControlCharacters(format(...args)));
+		forward(...args);
+	};
+	console.log = capture(originalError);
+	console.info = capture(originalError);
+	console.warn = capture(originalWarn);
+	console.error = capture(originalError);
+	const restoreConsole = () => {
+		console.log = originalLog;
+		console.info = originalInfo;
+		console.warn = originalWarn;
+		console.error = originalError;
+	};
+	const print = (report) => {
+		if (printed) return;
+		printed = true;
+		process.stdout.write(`${JSON.stringify(report)}\n`);
+	};
+	const onExit = (code) => {
+		const messages = run?.messages ?? [];
+		print(code === 0 ? endGenerationRun({ ok: true }) : endGenerationRun({
+			ok: false,
+			error: failureMessage(messages)
+		}));
+	};
+	process.once("exit", onExit);
+	try {
+		await action(data);
+		print(endGenerationRun({ ok: true }));
+	} catch (error) {
+		print(endGenerationRun({
+			ok: false,
+			error: error instanceof Error ? error.message : String(error)
+		}));
+		throw error;
+	} finally {
+		process.off("exit", onExit);
+		restoreConsole();
+	}
+}
+/** The options every generation command accepts, for `command({ options })`. */
+const generationOutputOptions = [{
+	text: "--dry-run",
+	description: "Preview the files that would be written or skipped without writing anything",
+	type: "boolean"
+}, {
+	text: "--json",
+	description: "Print one JSON report on stdout (files written, files skipped because they exist, messages)",
+	type: "boolean"
+}];
+
+//#endregion
+export { currentGenerationRun, generationOutputOptions, hasPendingContentUnder, isGenerationDryRun, pendingGeneratedContent, recordGeneratedFile, recordSkippedFile, runGenerationCommand, setGenerationDetail, setPendingGeneratedContent, toReportPath };
+//# sourceMappingURL=generation-run.mjs.map

package/esm/generations/generation-run.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-run.mjs","names":[],"sources":["../../../../../../../../packages/core/src/generations/generation-run.ts"],"sourcesContent":["import path from \"node:path\";\nimport { format, stripVTControlCharacters } from \"node:util\";\nimport type { CommandActionData } from \"../commands/types\";\n\n/**\n * What a generation command did (or, in a dry run, would do) to one file.\n *\n * - `create` — the file did not exist and is written.\n * - `overwrite` — the file existed and is replaced because `--force` was given.\n * - `update` — an existing file is edited in place (a route appended, a key merged).\n * - `unchanged` — the file already holds exactly the generated content.\n * - `skip` — the file exists and is left alone; `reason` says why.\n */\nexport type GenerationFileAction = \"create\" | \"overwrite\" | \"update\" | \"unchanged\" | \"skip\";\n\nexport type GenerationFileRecord = {\n  /** Path relative to the current working directory, with `/` separators. */\n  path: string;\n  type: GenerationFileAction;\n  reason?: string;\n};\n\n/**\n * The machine-readable result `--json` prints on stdout, one JSON document.\n *\n * `schemaVersion` changes only when a field is removed or changes meaning;\n * new fields may be added to version 1.\n */\nexport type GenerationReport = {\n  schemaVersion: 1;\n  /** The command as typed, e.g. `\"make endpoint\"` or `\"add\"`. */\n  command: string;\n  dryRun: boolean;\n  ok: boolean;\n  /** Files created, overwritten or updated (or, in a dry run, that would be). */\n  written: string[];\n  /** Files left alone because they already exist, with the reason. */\n  skipped: Array<{ path: string; reason: string }>;\n  /** Every file the command touched, in the order it touched them. */\n  files: GenerationFileRecord[];\n  /** Command-specific facts, e.g. the dependencies `add` installs. */\n  details: Record<string, unknown>;\n  /** Everything the command printed, without colours. */\n  messages: string[];\n  /** Why the command failed, when `ok` is false. */\n  error?: string;\n};\n\ntype GenerationRunState = {\n  command: string;\n  dryRun: boolean;\n  files: Map<string, GenerationFileRecord>;\n  /** Dry-run overlay: content a real run would have written, keyed by absolute path. */\n  pending: Map<string, string>;\n  details: Record<string, unknown>;\n  messages: string[];\n};\n\nlet activeRun: GenerationRunState | undefined;\n\n/** Render an absolute path relative to the cwd, `/`-separated, for reports and logs. */\nexport function toReportPath(target: string): string {\n  const relative = path.relative(process.cwd(), path.resolve(target)) || target;\n\n  return relative.split(path.sep).join(\"/\");\n}\n\n/**\n * Start recording a generation command. Every write made through\n * `generation-fs` (and the `generate.*` writer) is recorded until\n * {@link endGenerationRun}; in a dry run nothing reaches the disk.\n */\nexport function beginGenerationRun(options: { command: string; dryRun: boolean }): void {\n  activeRun = {\n    command: options.command,\n    dryRun: options.dryRun,\n    files: new Map(),\n    pending: new Map(),\n    details: {},\n    messages: [],\n  };\n}\n\n/** The run being recorded, if any. */\nexport function currentGenerationRun(): Readonly<GenerationRunState> | undefined {\n  return activeRun;\n}\n\n/** Whether the current generation command is a dry run. */\nexport function isGenerationDryRun(): boolean {\n  return activeRun?.dryRun === true;\n}\n\n/**\n * Record what happened to one file. A file first created and later edited in\n * the same run stays `create`: the report describes the run's net effect.\n */\nexport function recordGeneratedFile(\n  target: string,\n  type: GenerationFileAction,\n  reason?: string,\n): void {\n  if (!activeRun) return;\n\n  const key = toReportPath(target);\n  const previous = activeRun.files.get(key);\n\n  if (previous?.type === \"create\" && type !== \"skip\") return;\n\n  activeRun.files.set(\n    key,\n    reason === undefined ? { path: key, type } : { path: key, type, reason },\n  );\n}\n\n/** Record a file the command deliberately left alone. */\nexport function recordSkippedFile(target: string, reason: string): void {\n  recordGeneratedFile(target, \"skip\", reason);\n}\n\n/** Attach a command-specific fact to the report, e.g. `dependencies`. */\nexport function setGenerationDetail(key: string, value: unknown): void {\n  if (!activeRun) return;\n\n  activeRun.details[key] = value;\n}\n\n/** The dry-run overlay content for `target`, when this run \"wrote\" it. */\nexport function pendingGeneratedContent(target: string): string | undefined {\n  return activeRun?.pending.get(path.resolve(target));\n}\n\n/** Keep `content` as what a dry run would have written to `target`. */\nexport function setPendingGeneratedContent(target: string, content: string): void {\n  activeRun?.pending.set(path.resolve(target), content);\n}\n\n/** Whether any pending dry-run file lives under `directory`. */\nexport function hasPendingContentUnder(directory: string): boolean {\n  if (!activeRun) return false;\n\n  const prefix = path.resolve(directory) + path.sep;\n\n  for (const file of activeRun.pending.keys()) {\n    if (file.startsWith(prefix)) return true;\n  }\n\n  return false;\n}\n\n/** Stop recording and build the report. */\nexport function endGenerationRun(result: { ok: boolean; error?: string }): GenerationReport {\n  const run = activeRun;\n\n  activeRun = undefined;\n\n  const files = run ? [...run.files.values()] : [];\n  const report: GenerationReport = {\n    schemaVersion: 1,\n    command: run?.command ?? \"\",\n    dryRun: run?.dryRun ?? false,\n    ok: result.ok,\n    written: files\n      .filter(\n        (file) => file.type === \"create\" || file.type === \"overwrite\" || file.type === \"update\",\n      )\n      .map((file) => file.path),\n    skipped: files\n      .filter((file) => file.type === \"skip\")\n      .map((file) => ({ path: file.path, reason: file.reason ?? \"exists\" })),\n    files,\n    details: run?.details ?? {},\n    messages: run?.messages ?? [],\n  };\n\n  if (result.error !== undefined) report.error = result.error;\n\n  return report;\n}\n\n/**\n * Pick the line that explains a failure from what the command printed: the\n * first `Error…` line, else the last line.\n */\nfunction failureMessage(messages: readonly string[]): string {\n  const errorLine = messages.find((message) => /^\\s*(?:✖\\s*)?Error\\b/.test(message));\n\n  return (errorLine ?? messages[messages.length - 1] ?? \"The command failed.\").trim();\n}\n\n/**\n * Run a `make` / `generate.*` / `add` action under the recorder.\n *\n * `--dry-run` writes nothing. `--json` sends everything the command prints\n * to stderr and prints exactly one {@link GenerationReport} on stdout — also\n * when the command fails, including through `process.exit(1)`, so a caller\n * parsing stdout always gets a document.\n */\nexport async function runGenerationCommand(\n  command: string,\n  data: CommandActionData,\n  action: (data: CommandActionData) => Promise<void>,\n): Promise<void> {\n  const json = data.options.json === true || data.options.j === true;\n  const dryRun = data.options.dryRun === true;\n\n  beginGenerationRun({ command, dryRun });\n\n  if (!json) {\n    try {\n      await action(data);\n    } finally {\n      endGenerationRun({ ok: true });\n    }\n\n    return;\n  }\n\n  const run = activeRun;\n  const originalLog = console.log;\n  const originalInfo = console.info;\n  const originalWarn = console.warn;\n  const originalError = console.error;\n  let printed = false;\n\n  const capture =\n    (forward: (...args: unknown[]) => void) =>\n    (...args: unknown[]): void => {\n      run?.messages.push(stripVTControlCharacters(format(...args)));\n      forward(...args);\n    };\n\n  // stdout carries the report and nothing else.\n  console.log = capture(originalError);\n  console.info = capture(originalError);\n  console.warn = capture(originalWarn);\n  console.error = capture(originalError);\n\n  const restoreConsole = (): void => {\n    console.log = originalLog;\n    console.info = originalInfo;\n    console.warn = originalWarn;\n    console.error = originalError;\n  };\n\n  const print = (report: GenerationReport): void => {\n    if (printed) return;\n\n    printed = true;\n    process.stdout.write(`${JSON.stringify(report)}\\n`);\n  };\n\n  // Generators stop with `process.exit(1)` on bad input. The report still has\n  // to reach stdout, and `exit` listeners run synchronously before the process\n  // ends (stdout writes to a pipe or file are synchronous on Linux and macOS).\n  const onExit = (code: number): void => {\n    const messages = run?.messages ?? [];\n\n    print(\n      code === 0\n        ? endGenerationRun({ ok: true })\n        : endGenerationRun({ ok: false, error: failureMessage(messages) }),\n    );\n  };\n\n  process.once(\"exit\", onExit);\n\n  try {\n    await action(data);\n    print(endGenerationRun({ ok: true }));\n  } catch (error) {\n    print(\n      endGenerationRun({\n        ok: false,\n        error: error instanceof Error ? error.message : String(error),\n      }),\n    );\n\n    throw error;\n  } finally {\n    process.off(\"exit\", onExit);\n    restoreConsole();\n  }\n}\n\n/** The options every generation command accepts, for `command({ options })`. */\nexport const generationOutputOptions = [\n  {\n    text: \"--dry-run\",\n    description: \"Preview the files that would be written or skipped without writing anything\",\n    type: \"boolean\" as const,\n  },\n  {\n    text: \"--json\",\n    description:\n      \"Print one JSON report on stdout (files written, files skipped because they exist, messages)\",\n    type: \"boolean\" as const,\n  },\n];\n"],"mappings":"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"}

package/esm/generations/stubs.mjs

@@ -660,26 +660,168 @@ const notificationLocalesStub = `{
   "notFound": { "en": "Notification not found" }
 }
 `;
-/**
-* A controller spec for the notifications module, written only when the app
-* has the test feature. It checks the one thing true in every app — the route
-* refuses a request with no signed-in user — and leaves the signed-in cases to
-* the app, which owns its login helper.
-*/
+/** Shared fixtures for the generated signed-in notification controller specs. */
+const notificationTestFixtureStub = `import type { Auth } from "@warlock.js/auth";
+import type { ChildModel } from "@warlock.js/cascade";
+import { config } from "@warlock.js/core";
+import { actingAs, type AuthenticatedTestClient } from "@warlock.js/core/tests";
+import { randomUUID } from "node:crypto";
+import { Notification } from "../models/notification/notification.model";
+
+/** Isolated recipients and rows; adjust user fields if your auth model requires more. */
+export async function createNotificationTestFixture() {
+  const User = config.key<ChildModel<Auth>>("auth.userType.user");
+  if (!User) throw new Error("Notification specs need the configured auth.userType.user model.");
+  const users: Auth[] = [];
+  const clients: AuthenticatedTestClient[] = [];
+  const rows: Notification[] = [];
+
+  async function cleanup() {
+    const credentials = await Promise.allSettled(
+      clients.splice(0).map((client) => client.dispose()),
+    );
+    const notifications = await Promise.allSettled(
+      rows.splice(0).map((row) => row.destroy({ strategy: "permanent" })),
+    );
+    const recipients = await Promise.allSettled(
+      users.splice(0).map((user) => user.destroy({ strategy: "permanent" })),
+    );
+    const errors = [...credentials, ...notifications, ...recipients]
+      .filter((result): result is PromiseRejectedResult => result.status === "rejected")
+      .map((result) => result.reason);
+    if (errors.length) throw new AggregateError(errors, "Notification fixture cleanup failed.");
+  }
+
+  const createUser = async () => {
+    const user = await User.create({
+      name: "Notification test user",
+      email: "notifications-" + randomUUID() + "@example.test",
+      password: "test-password",
+    });
+    users.push(user);
+    return user;
+  };
+  const signIn = async (user: Auth) => {
+    const client = await actingAs(user);
+    clients.push(client);
+    return client;
+  };
+  const createNotification = async (recipientId: string | number, title: string, readAt?: Date) => {
+    const row = await Notification.create({
+      user_id: recipientId,
+      type: "test",
+      title,
+      read_at: readAt,
+    });
+    rows.push(row);
+    return row;
+  };
+
+  try {
+    const user = await createUser();
+    const otherUser = await createUser();
+    const client = await signIn(user);
+    const otherClient = await signIn(otherUser);
+    const own = await createNotification(user.id, "Own unread notification");
+    const alreadyRead = await createNotification(user.id, "Own read notification", new Date());
+    const foreign = await createNotification(otherUser.id, "Other user's notification");
+    await createNotification(otherUser.id, "Other user's second notification");
+    return { user, otherUser, client, otherClient, own, alreadyRead, foreign, cleanup };
+  } catch (error) {
+    // Preserve the setup failure after attempting every owned resource's cleanup.
+    await cleanup().catch(() => undefined);
+    throw error;
+  }
+}
+`;
+/** A spec for each generated controller, including authenticated recipient isolation. */
 function notificationControllerSpecStub(method, path) {
 	const helper = method === "GET" ? "testGet" : "testPatch";
-	return `import { ${helper} } from "@warlock.js/core/tests";
-import { describe, expect, it } from "vitest";
+	let signedInCases;
+	if (path === "/notifications") signedInCases = `    it("lists only the signed-in recipient's rows, ignoring a forged recipient query", async () => {
+      const response = await fixture.client.get(
+        "/notifications?recipientId=" + fixture.otherUser.id,
+      );
+      const body = await expectJson<{ notifications: { id: string | number }[] }>(response);
+      expect(body.notifications.map((row) => row.id)).toEqual(
+        expect.arrayContaining([fixture.own.id, fixture.alreadyRead.id]),
+      );
+      expect(body.notifications).toHaveLength(2);
+    });
+
+    it("applies unread and paging query filters", async () => {
+      const response = await fixture.client.get("/notifications?unread=true&limit=1");
+      const body = await expectJson<{ notifications: { id: string | number }[] }>(response);
+      expect(body.notifications.map((row) => row.id)).toEqual([fixture.own.id]);
+    });
+
+    it("rejects a list limit above the schema's cap", async () => {
+      expect((await fixture.client.get("/notifications?limit=999")).status).toBe(422);
+    });`;
+	else if (path === "/notifications/unread-count") signedInCases = `    it("counts only this recipient's unread notifications", async () => {
+      const own = await expectJson<{ count: number }>(
+        await fixture.client.get("/notifications/unread-count"),
+      );
+      const other = await expectJson<{ count: number }>(
+        await fixture.otherClient.get("/notifications/unread-count"),
+      );
+      expect(own.count).toBe(1);
+      expect(other.count).toBe(2);
+    });`;
+	else if (path === "/notifications/read-all") signedInCases = `    it("marks only this recipient's unread rows and leaves another recipient unchanged", async () => {
+      const body = await expectJson<{ count: number }>(
+        await fixture.client.patch("/notifications/read-all"),
+      );
+      expect(body.count).toBe(1);
+      expect((await Notification.find(fixture.own.id))?.isRead).toBe(true);
+      expect((await Notification.find(fixture.foreign.id))?.isRead).toBe(false);
+      const other = await expectJson<{ count: number }>(
+        await fixture.otherClient.get("/notifications/unread-count"),
+      );
+      expect(other.count).toBe(2);
+      const again = await expectJson<{ count: number }>(
+        await fixture.client.patch("/notifications/read-all"),
+      );
+      expect(again.count).toBe(0);
+    });`;
+	else signedInCases = `    it("marks its own notification read and returns it", async () => {
+      const response = await fixture.client.patch("/notifications/" + fixture.own.id + "/read");
+      const body = await expectJson<{
+        notification: { id: string | number; readAt?: string | null };
+      }>(response);
+      expect(body.notification.id).toBe(fixture.own.id);
+      expect(body.notification.readAt).toBeTruthy();
+      expect((await Notification.find(fixture.own.id))?.isRead).toBe(true);
+    });
+
+    it("answers 404 for another recipient's notification without changing it", async () => {
+      const response = await fixture.client.patch("/notifications/" + fixture.foreign.id + "/read");
+      expect(response.status).toBe(404);
+      expect((await Notification.find(fixture.foreign.id))?.isRead).toBe(false);
+    });`;
+	return `import { expectJson, ${helper} } from "@warlock.js/core/tests";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+${method === "PATCH" ? "import { Notification } from \"../models/notification/notification.model\";\n" : ""}import { createNotificationTestFixture } from "../tests/notifications.fixture";
 
 describe("${method} ${path}", () => {
   it("answers 401 without a signed-in user", async () => {
     const response = await ${helper}("${path}");
-
     expect(response.status).toBe(401);
   });
 
-  // Add the signed-in cases with your app's login helper, including that
-  // another user's notifications are never returned or changed.
+  describe("signed in", () => {
+    let fixture: Awaited<ReturnType<typeof createNotificationTestFixture>> | undefined;
+    beforeEach(async () => {
+      fixture = await createNotificationTestFixture();
+    });
+    afterEach(async () => {
+      const current = fixture;
+      fixture = undefined;
+      await current?.cleanup();
+    });
+
+${signedInCases.replaceAll("fixture.", "fixture!.")}
+  });
 });
 `;
 }
@@ -781,7 +923,7 @@ contactController.validation = { schema: contactSchema };
 const webContactRoutesStub = `import { router } from "@warlock.js/core";
 import { contactController } from "./controllers/contact.controller";
 
-router.post("/api/contact", contactController);
+router.post("/api/contact", contactController, { public: true });
 `;
 /**
 * `src/web/index.register.ts` — universal static setup for the starter page.
@@ -1047,5 +1189,5 @@ function ContactMessage() {
 `;
 
 //#endregion
-export { accessConfigStub, accessResolverStub, accessRoleMigrationStub, accessRoleModelIndexStub, accessRoleModelStub, accessUserRoleMigrationStub, accessUserRoleModelIndexStub, accessUserRoleModelStub, aiConfigStub, communicatorsConfigStub, listNotificationsControllerStub, listNotificationsSchemaStub, markAllNotificationsReadControllerStub, markNotificationReadControllerStub, markNotificationReadServiceStub, notificationControllerSpecStub, notificationLocalesStub, notificationMigrationStub, notificationModelStub, notificationResourceStub, notificationRoutesStub, notificationsConfigStub, notificationsRequestTypeStub, socketConfigStub, unreadNotificationsCountControllerStub, webContactControllerStub, webContactRoutesStub, webHomePageStub, webHomeRegisterStub, webRootStub };
+export { accessConfigStub, accessResolverStub, accessRoleMigrationStub, accessRoleModelIndexStub, accessRoleModelStub, accessUserRoleMigrationStub, accessUserRoleModelIndexStub, accessUserRoleModelStub, aiConfigStub, communicatorsConfigStub, listNotificationsControllerStub, listNotificationsSchemaStub, markAllNotificationsReadControllerStub, markNotificationReadControllerStub, markNotificationReadServiceStub, notificationControllerSpecStub, notificationLocalesStub, notificationMigrationStub, notificationModelStub, notificationResourceStub, notificationRoutesStub, notificationTestFixtureStub, notificationsConfigStub, notificationsRequestTypeStub, socketConfigStub, unreadNotificationsCountControllerStub, webContactControllerStub, webContactRoutesStub, webHomePageStub, webHomeRegisterStub, webRootStub };
 //# sourceMappingURL=stubs.mjs.map