create-warlock 5.16.0 → 5.17.0

package/esm/prompts/ask-agent-targets.mjs

@@ -0,0 +1,87 @@
+import { BUILTIN_AGENT_KIT_TARGETS, DEFAULT_AGENT_KIT_TARGET, getValidAgentKitTargets } from "../features/agent-kit-targets.mjs";
+import { cancel, isCancel, multiselect } from "@clack/prompts";
+
+//#region ../create-warlock/src/prompts/ask-agent-targets.ts
+/**
+* Which `agent-kit` targets to derive per-agent docs and skills for.
+*
+* The valid target list is not a literal we own — it comes from the installed
+* `@mongez/agent-kit`, or a cached network fetch, and
+* {@link getValidAgentKitTargets} THROWS when neither is available. That is
+* the right behaviour for `--agents=something-unusual`, where guessing would
+* be worse than failing. It is the wrong behaviour here: this prompt sits
+* five questions into the wizard, and an offline laptop must not lose four
+* already-given answers to a failed HTTP request.
+*
+* So an unreachable list is not fatal — it narrows the menu to the built-in
+* targets and SAYS SO, rather than either crashing or silently pretending
+* that is the whole list.
+*/
+async function askAgentTargets(requested) {
+	const { targets: known, complete } = await availableTargets();
+	const targets = reconcileRequested(requested, known, complete);
+	const answer = await multiselect({
+		message: complete ? "Which coding agents should this project be set up for?" : "Which coding agents should this project be set up for? (offline — showing built-in targets only)",
+		options: targets.map((target) => ({
+			value: target,
+			label: target
+		})),
+		initialValues: initialSelection(requested, targets),
+		required: false
+	});
+	if (isCancel(answer)) {
+		cancel("Agent selection cancelled");
+		process.exit(0);
+	}
+	const selected = answer;
+	return selected.length > 0 ? selected : [DEFAULT_AGENT_KIT_TARGET];
+}
+/**
+* The target list, plus whether it is the REAL one. `complete: false` means
+* the lookup failed and these are only the offline built-ins.
+*/
+async function availableTargets() {
+	try {
+		return {
+			targets: await getValidAgentKitTargets(),
+			complete: true
+		};
+	} catch {
+		return {
+			targets: [...BUILTIN_AGENT_KIT_TARGETS],
+			complete: false
+		};
+	}
+}
+/**
+* What `--agents` asked for has to end up among the OPTIONS, or it would be
+* pre-ticked invisibly and then silently dropped — the same defect this
+* wizard's other flags already had.
+*
+* With a complete list, an unrecognised target is refused, naming the valid
+* ones, exactly as `resolveAgentTargets` does for the non-interactive path.
+* With an incomplete one, we have no authority to call anything invalid, so
+* the requested targets are offered alongside the built-ins instead of being
+* judged.
+*/
+function reconcileRequested(requested, known, complete) {
+	if (!requested || requested.length === 0) return known;
+	const unknown = requested.filter((target) => !known.includes(target));
+	if (unknown.length === 0) return known;
+	if (complete) {
+		cancel(`Unknown agent-kit target(s): ${unknown.join(", ")} — valid targets: ${known.slice().sort().join(", ")}`);
+		process.exit(1);
+	}
+	return [...known, ...unknown];
+}
+/**
+* Pre-tick what `--agents` asked for. Everything it names is among the
+* options by now, so nothing is filtered away here.
+*/
+function initialSelection(requested, targets) {
+	return (requested && requested.length > 0 ? requested : [DEFAULT_AGENT_KIT_TARGET]).filter((target) => targets.includes(target));
+}
+
+//#endregion
+export { askAgentTargets };
+//# sourceMappingURL=ask-agent-targets.mjs.map

package/esm/prompts/ask-agent-targets.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-agent-targets.mjs","names":[],"sources":["../../../../../../create-warlock/src/prompts/ask-agent-targets.ts"],"sourcesContent":["import { cancel, isCancel, multiselect } from \"@clack/prompts\";\nimport {\n  BUILTIN_AGENT_KIT_TARGETS,\n  DEFAULT_AGENT_KIT_TARGET,\n  getValidAgentKitTargets,\n} from \"../features/agent-kit-targets\";\n\n/**\n * Which `agent-kit` targets to derive per-agent docs and skills for.\n *\n * The valid target list is not a literal we own — it comes from the installed\n * `@mongez/agent-kit`, or a cached network fetch, and\n * {@link getValidAgentKitTargets} THROWS when neither is available. That is\n * the right behaviour for `--agents=something-unusual`, where guessing would\n * be worse than failing. It is the wrong behaviour here: this prompt sits\n * five questions into the wizard, and an offline laptop must not lose four\n * already-given answers to a failed HTTP request.\n *\n * So an unreachable list is not fatal — it narrows the menu to the built-in\n * targets and SAYS SO, rather than either crashing or silently pretending\n * that is the whole list.\n */\nexport async function askAgentTargets(\n  requested: string[] | undefined,\n): Promise<string[]> {\n  const { targets: known, complete } = await availableTargets();\n  const targets = reconcileRequested(requested, known, complete);\n\n  const answer = await multiselect({\n    message: complete\n      ? \"Which coding agents should this project be set up for?\"\n      : \"Which coding agents should this project be set up for? (offline — showing built-in targets only)\",\n    options: targets.map(target => ({ value: target, label: target })),\n    initialValues: initialSelection(requested, targets),\n    required: false,\n  });\n\n  if (isCancel(answer)) {\n    cancel(\"Agent selection cancelled\");\n    process.exit(0);\n  }\n\n  const selected = answer as string[];\n\n  return selected.length > 0 ? selected : [DEFAULT_AGENT_KIT_TARGET];\n}\n\n/**\n * The target list, plus whether it is the REAL one. `complete: false` means\n * the lookup failed and these are only the offline built-ins.\n */\nasync function availableTargets(): Promise<{\n  targets: string[];\n  complete: boolean;\n}> {\n  try {\n    return { targets: await getValidAgentKitTargets(), complete: true };\n  } catch {\n    return { targets: [...BUILTIN_AGENT_KIT_TARGETS], complete: false };\n  }\n}\n\n/**\n * What `--agents` asked for has to end up among the OPTIONS, or it would be\n * pre-ticked invisibly and then silently dropped — the same defect this\n * wizard's other flags already had.\n *\n * With a complete list, an unrecognised target is refused, naming the valid\n * ones, exactly as `resolveAgentTargets` does for the non-interactive path.\n * With an incomplete one, we have no authority to call anything invalid, so\n * the requested targets are offered alongside the built-ins instead of being\n * judged.\n */\nfunction reconcileRequested(\n  requested: string[] | undefined,\n  known: string[],\n  complete: boolean,\n): string[] {\n  if (!requested || requested.length === 0) return known;\n\n  const unknown = requested.filter(target => !known.includes(target));\n\n  if (unknown.length === 0) return known;\n\n  if (complete) {\n    cancel(\n      `Unknown agent-kit target(s): ${unknown.join(\", \")} — valid targets: ${known\n        .slice()\n        .sort()\n        .join(\", \")}`,\n    );\n    process.exit(1);\n  }\n\n  return [...known, ...unknown];\n}\n\n/**\n * Pre-tick what `--agents` asked for. Everything it names is among the\n * options by now, so nothing is filtered away here.\n */\nfunction initialSelection(\n  requested: string[] | undefined,\n  targets: string[],\n): string[] {\n  const wanted =\n    requested && requested.length > 0 ? requested : [DEFAULT_AGENT_KIT_TARGET];\n\n  return wanted.filter(target => targets.includes(target));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAsBA,eAAsB,gBACpB,WACmB;CACnB,MAAM,EAAE,SAAS,OAAO,aAAa,MAAM,iBAAiB;CAC5D,MAAM,UAAU,mBAAmB,WAAW,OAAO,QAAQ;CAE7D,MAAM,SAAS,MAAM,YAAY;EAC/B,SAAS,WACL,2DACA;EACJ,SAAS,QAAQ,KAAI,YAAW;GAAE,OAAO;GAAQ,OAAO;EAAO,EAAE;EACjE,eAAe,iBAAiB,WAAW,OAAO;EAClD,UAAU;CACZ,CAAC;CAED,IAAI,SAAS,MAAM,GAAG;EACpB,OAAO,2BAA2B;EAClC,QAAQ,KAAK,CAAC;CAChB;CAEA,MAAM,WAAW;CAEjB,OAAO,SAAS,SAAS,IAAI,WAAW,CAAC,wBAAwB;AACnE;;;;;AAMA,eAAe,mBAGZ;CACD,IAAI;EACF,OAAO;GAAE,SAAS,MAAM,wBAAwB;GAAG,UAAU;EAAK;CACpE,QAAQ;EACN,OAAO;GAAE,SAAS,CAAC,GAAG,yBAAyB;GAAG,UAAU;EAAM;CACpE;AACF;;;;;;;;;;;;AAaA,SAAS,mBACP,WACA,OACA,UACU;CACV,IAAI,CAAC,aAAa,UAAU,WAAW,GAAG,OAAO;CAEjD,MAAM,UAAU,UAAU,QAAO,WAAU,CAAC,MAAM,SAAS,MAAM,CAAC;CAElE,IAAI,QAAQ,WAAW,GAAG,OAAO;CAEjC,IAAI,UAAU;EACZ,OACE,gCAAgC,QAAQ,KAAK,IAAI,EAAE,oBAAoB,MACpE,MAAM,CAAC,CACP,KAAK,CAAC,CACN,KAAK,IAAI,GACd;EACA,QAAQ,KAAK,CAAC;CAChB;CAEA,OAAO,CAAC,GAAG,OAAO,GAAG,OAAO;AAC9B;;;;;AAMA,SAAS,iBACP,WACA,SACU;CAIV,QAFE,aAAa,UAAU,SAAS,IAAI,YAAY,CAAC,wBAAwB,EAE9D,CAAC,QAAO,WAAU,QAAQ,SAAS,MAAM,CAAC;AACzD"}

package/esm/prompts/ask-project-name.mjs

@@ -0,0 +1,25 @@
+import { cancel, isCancel, text } from "@clack/prompts";
+
+//#region ../create-warlock/src/prompts/ask-project-name.ts
+/**
+* The project name is the one answer with no sane default, so every
+* interactive path has to ask it. It lives here so the default path and the
+* full wizard ask it with the SAME wording and the same cancel handling —
+* and so a name already collected by one path can simply be handed to the
+* other instead of being asked a second time.
+*/
+async function askProjectName() {
+	const answer = await text({
+		message: "What shall we call your project?",
+		placeholder: "my-warlock-app"
+	});
+	if (isCancel(answer) || !answer.trim()) {
+		cancel("A project name is required to continue");
+		process.exit(0);
+	}
+	return answer;
+}
+
+//#endregion
+export { askProjectName };
+//# sourceMappingURL=ask-project-name.mjs.map

package/esm/prompts/ask-project-name.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-project-name.mjs","names":[],"sources":["../../../../../../create-warlock/src/prompts/ask-project-name.ts"],"sourcesContent":["import { cancel, isCancel, text } from \"@clack/prompts\";\n\n/**\n * The project name is the one answer with no sane default, so every\n * interactive path has to ask it. It lives here so the default path and the\n * full wizard ask it with the SAME wording and the same cancel handling —\n * and so a name already collected by one path can simply be handed to the\n * other instead of being asked a second time.\n */\nexport async function askProjectName(): Promise<string> {\n  const answer = await text({\n    message: \"What shall we call your project?\",\n    placeholder: \"my-warlock-app\",\n  });\n\n  if (isCancel(answer) || !answer.trim()) {\n    cancel(\"A project name is required to continue\");\n    process.exit(0);\n  }\n\n  return answer;\n}\n"],"mappings":";;;;;;;;;;AASA,eAAsB,iBAAkC;CACtD,MAAM,SAAS,MAAM,KAAK;EACxB,SAAS;EACT,aAAa;CACf,CAAC;CAED,IAAI,SAAS,MAAM,KAAK,CAAC,OAAO,KAAK,GAAG;EACtC,OAAO,wCAAwC;EAC/C,QAAQ,KAAK,CAAC;CAChB;CAEA,OAAO;AACT"}

package/esm/prompts/ask-stack.mjs

@@ -8,19 +8,32 @@ import { cancel, isCancel, select } from "@clack/prompts";
 * of the generated project — every other choice (database, features,
 * package manager, agent-kit targets, …) is reversible within minutes and
 * ships as a flag with a default instead.
+*
+* The third entry is not a third stack: `customize` selects the FLOW, handing
+* the run to the full wizard (`--customize`) so every one of those reversible
+* choices gets asked instead of defaulted. It sits in this menu because a flag
+* nobody is told about is a feature nobody has.
 */
 async function askStack() {
 	const answer = await select({
 		message: "What are we building?",
-		options: [{
-			value: "api",
-			label: "API only",
-			hint: "A REST/GraphQL API, no server-rendered pages"
-		}, {
-			value: "web",
-			label: "Full-stack web",
-			hint: "API + server-rendered React pages (SSR)"
-		}],
+		options: [
+			{
+				value: "api",
+				label: "API only",
+				hint: "A REST API, no server-rendered pages"
+			},
+			{
+				value: "web",
+				label: "Full-stack web",
+				hint: "API + server-rendered React pages (SSR)"
+			},
+			{
+				value: "customize",
+				label: "Customize",
+				hint: "Pick package manager, database, features, AI providers and coding agents one by one"
+			}
+		],
 		initialValue: "api"
 	});
 	if (isCancel(answer)) {

package/esm/prompts/ask-stack.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ask-stack.mjs","names":[],"sources":["../../../../../../create-warlock/src/prompts/ask-stack.ts"],"sourcesContent":["import { cancel, isCancel, select } from \"@clack/prompts\";\nimport type { Stack } from \"../commands/create-new-app/types\";\n\n/**\n * The ONE structural question the default (non-`--interactive`) interactive\n * path is allowed to ask: does the generated app need server-rendered web\n * pages, or is it an API only? This is the sole fork that changes the shape\n * of the generated project — every other choice (database, features,\n * package manager, agent-kit targets, …) is reversible within minutes and\n * ships as a flag with a default instead.\n */\nexport async function askStack(): Promise<Stack> {\n  const answer = await select({\n    message: \"What are we building?\",\n    options: [\n      {\n        value: \"api\",\n        label: \"API only\",\n        hint: \"A REST/GraphQL API, no server-rendered pages\",\n      },\n      {\n        value: \"web\",\n        label: \"Full-stack web\",\n        hint: \"API + server-rendered React pages (SSR)\",\n      },\n    ],\n    initialValue: \"api\",\n  });\n\n  if (isCancel(answer)) {\n    cancel(\"Setup cancelled\");\n    process.exit(0);\n  }\n\n  return answer as Stack;\n}\n"],"mappings":";;;;;;;;;;;AAWA,eAAsB,WAA2B;CAC/C,MAAM,SAAS,MAAM,OAAO;EAC1B,SAAS;EACT,SAAS,CACP;GACE,OAAO;GACP,OAAO;GACP,MAAM;EACR,GACA;GACE,OAAO;GACP,OAAO;GACP,MAAM;EACR,CACF;EACA,cAAc;CAChB,CAAC;CAED,IAAI,SAAS,MAAM,GAAG;EACpB,OAAO,iBAAiB;EACxB,QAAQ,KAAK,CAAC;CAChB;CAEA,OAAO;AACT"}
+{"version":3,"file":"ask-stack.mjs","names":[],"sources":["../../../../../../create-warlock/src/prompts/ask-stack.ts"],"sourcesContent":["import { cancel, isCancel, select } from \"@clack/prompts\";\nimport type { SetupChoice } from \"../commands/create-new-app/types\";\n\n/**\n * The ONE structural question the default (non-`--interactive`) interactive\n * path is allowed to ask: does the generated app need server-rendered web\n * pages, or is it an API only? This is the sole fork that changes the shape\n * of the generated project — every other choice (database, features,\n * package manager, agent-kit targets, …) is reversible within minutes and\n * ships as a flag with a default instead.\n *\n * The third entry is not a third stack: `customize` selects the FLOW, handing\n * the run to the full wizard (`--customize`) so every one of those reversible\n * choices gets asked instead of defaulted. It sits in this menu because a flag\n * nobody is told about is a feature nobody has.\n */\nexport async function askStack(): Promise<SetupChoice> {\n  const answer = await select({\n    message: \"What are we building?\",\n    options: [\n      {\n        value: \"api\",\n        label: \"API only\",\n        hint: \"A REST API, no server-rendered pages\",\n      },\n      {\n        value: \"web\",\n        label: \"Full-stack web\",\n        hint: \"API + server-rendered React pages (SSR)\",\n      },\n      {\n        value: \"customize\",\n        label: \"Customize\",\n        hint: \"Pick package manager, database, features, AI providers and coding agents one by one\",\n      },\n    ],\n    initialValue: \"api\",\n  });\n\n  if (isCancel(answer)) {\n    cancel(\"Setup cancelled\");\n    process.exit(0);\n  }\n\n  return answer as SetupChoice;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,eAAsB,WAAiC;CACrD,MAAM,SAAS,MAAM,OAAO;EAC1B,SAAS;EACT,SAAS;GACP;IACE,OAAO;IACP,OAAO;IACP,MAAM;GACR;GACA;IACE,OAAO;IACP,OAAO;IACP,MAAM;GACR;GACA;IACE,OAAO;IACP,OAAO;IACP,MAAM;GACR;EACF;EACA,cAAc;CAChB,CAAC;CAED,IAAI,SAAS,MAAM,GAAG;EACpB,OAAO,iBAAiB;EACxB,QAAQ,KAAK,CAAC;CAChB;CAEA,OAAO;AACT"}

package/esm/summary.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"summary.mjs","names":[],"sources":["../../../../../create-warlock/src/summary.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { getDatabaseLabel } from \"./features/database-drivers\";\nimport { AppOptions } from \"./commands/create-new-app/types\";\n\n/** What decisions.spec.ts / the terminal actually needs to render the summary. */\nexport type Decisions = {\n  packageManager: string;\n  options: AppOptions;\n};\n\n/**\n * Print what the scaffolder decided on the user's behalf, and how to change\n * each decision — required because almost every choice is now a default\n * rather than a prompt, so this is the only place a user sees them.\n */\nexport function printDecisionsSummary({ packageManager, options }: Decisions): void {\n  const databaseLabel = getDatabaseLabel(options.databaseDriver);\n\n  const headline = [\n    `Using ${packageManager}`,\n    `database: ${databaseLabel}`,\n    `agent-kit targets: ${options.agents.join(\", \")}`,\n  ].join(\" · \");\n\n  console.log();\n  console.log(colors.cyan(headline));\n  console.log(\n    colors.dim(\n      \"  change these — package manager: --pm, database: --db/--no-db, agents: --agents, \" +\n        \"features: --features, ai: --ai, git: --git/--no-git, jwt: --jwt/--no-jwt — \" +\n        \"or re-run with --interactive for the full wizard. Package-manager-level choices \" +\n        \"(husky, lint config, etc.) can also be edited directly in the generated project.\",\n    ),\n  );\n  console.log();\n}\n"],"mappings":";;;;;;;;;AAeA,SAAgB,sBAAsB,EAAE,gBAAgB,WAA4B;CAClF,MAAM,gBAAgB,iBAAiB,QAAQ,cAAc;CAE7D,MAAM,WAAW;EACf,SAAS;EACT,aAAa;EACb,sBAAsB,QAAQ,OAAO,KAAK,IAAI;CAChD,CAAC,CAAC,KAAK,KAAK;CAEZ,QAAQ,IAAI;CACZ,QAAQ,IAAI,OAAO,KAAK,QAAQ,CAAC;CACjC,QAAQ,IACN,OAAO,IACL,+TAIF,CACF;CACA,QAAQ,IAAI;AACd"}
+{"version":3,"file":"summary.mjs","names":[],"sources":["../../../../../create-warlock/src/summary.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { AppOptions } from \"./commands/create-new-app/types\";\nimport { getDatabaseLabel } from \"./features/database-drivers\";\n\n/** What decisions.spec.ts / the terminal actually needs to render the summary. */\nexport type Decisions = {\n  packageManager: string;\n  options: AppOptions;\n};\n\n/**\n * Print what the scaffolder decided on the user's behalf, and how to change\n * each decision — required because almost every choice is now a default\n * rather than a prompt, so this is the only place a user sees them.\n */\nexport function printDecisionsSummary({\n  packageManager,\n  options,\n}: Decisions): void {\n  const databaseLabel = getDatabaseLabel(options.databaseDriver);\n\n  const headline = [\n    `Using ${packageManager}`,\n    `database: ${databaseLabel}`,\n    `agent-kit targets: ${options.agents.join(\", \")}`,\n  ].join(\" · \");\n\n  console.log();\n  console.log(colors.cyan(headline));\n  console.log(\n    colors.dim(\n      \"  change these — package manager: --pm, database: --db/--no-db, agents: --agents, \" +\n        \"features: --features, ai: --ai, git: --git/--no-git, jwt: --jwt/--no-jwt — \" +\n        \"or re-run with --interactive for the full wizard. Package-manager-level choices \" +\n        \"(husky, lint config, etc.) can also be edited directly in the generated project.\",\n    ),\n  );\n  console.log();\n}\n"],"mappings":";;;;;;;;;AAeA,SAAgB,sBAAsB,EACpC,gBACA,WACkB;CAClB,MAAM,gBAAgB,iBAAiB,QAAQ,cAAc;CAE7D,MAAM,WAAW;EACf,SAAS;EACT,aAAa;EACb,sBAAsB,QAAQ,OAAO,KAAK,IAAI;CAChD,CAAC,CAAC,KAAK,KAAK;CAEZ,QAAQ,IAAI;CACZ,QAAQ,IAAI,OAAO,KAAK,QAAQ,CAAC;CACjC,QAAQ,IACN,OAAO,IACL,+TAIF,CACF;CACA,QAAQ,IAAI;AACd"}

package/llms-full.txt

@@ -136,7 +136,7 @@ my-app/
       ├─ auth/                  # controllers, schema, services, requests, utils, OTP model + migration
       ├─ users/                 # model, migration, resource, repository, create + list controllers, schema, events, seeds, commands
       ├─ posts/                 # sample module — model, migration, resource, schema, create + update controllers
-      ├─ uploads/               # file-serving controller (fetch-uploaded-file)
+      ├─ uploads/               # routes.ts mounts core's uploadedFileController; named image variants go in src/config/uploads.ts
       └─ shared/                # router/locale utils, home page, scheduler
 ```
 

package/package.json

@@ -12,7 +12,7 @@
   "dependencies": {
     "@clack/prompts": "^0.7.0",
     "@mongez/copper": "^2.1.2",
-    "@warlock.js/fs": "5.16.0",
+    "@warlock.js/fs": "5.17.0",
     "@mongez/reinforcements": "^4.0.1",
     "cross-spawn": "^7.0.3",
     "rimraf": "^6.0.1",
@@ -21,7 +21,7 @@
   "engines": {
     "node": ">=22.13"
   },
-  "version": "5.16.0",
+  "version": "5.17.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/create-a-warlock-project/SKILL.md

@@ -128,7 +128,7 @@ my-app/
       ├─ auth/                  # controllers, schema, services, requests, utils, OTP model + migration
       ├─ users/                 # model, migration, resource, repository, create + list controllers, schema, events, seeds, commands
       ├─ posts/                 # sample module — model, migration, resource, schema, create + update controllers
-      ├─ uploads/               # file-serving controller (fetch-uploaded-file)
+      ├─ uploads/               # routes.ts mounts core's uploadedFileController; named image variants go in src/config/uploads.ts
       └─ shared/                # router/locale utils, home page, scheduler
 ```
 

package/templates/warlock/AGENTS.md

@@ -59,6 +59,7 @@ automatically on `postinstall`).
 - **code-standards** — TypeScript style: `interface` (contracts) vs `type` (data),
   access modifiers on every class member, no `any`, single-responsibility files
   with the documented naming suffixes, JSDoc on the public surface.
+- **web-code-standards** — Thin web pages, service-owned data, feature hooks, and browser-safe rendering.
 - **data-and-persistence** — modeling, storing, and migrating data with
   `@warlock.js/cascade` (money as integer minor units, migrations, indexes).
 - **module-boundaries** — how modules under `src/app/**` relate; one domain noun

package/templates/warlock/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "warlock dev",
-    "build": "tsc && warlock build",
+    "build": "warlock generate.typings && tsc && warlock build",
     "start": "warlock start",
     "seed": "warlock seed",
     "migrate": "warlock migrate",
@@ -24,7 +24,7 @@
     "serve": "yarn build && nohup warlock start > /dev/null 2>&1",
     "lint": "npx eslint --fix ./src --max-warnings=0",
     "format": "npx prettier --write ./src/**/*.{js,jsx,ts,tsx,css,md,json} --config ./.prettierrc.json",
-    "tsc": "npx tsc --noEmit",
+    "tsc": "warlock generate.typings && npx tsc --noEmit",
     "postinstall": "agent-kit init && agent-kit sync || echo skills-sync-skipped",
     "skills:sync": "agent-kit sync",
     "skills:watch": "agent-kit watch",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@mongez/reinforcements": "^4.0.1",
-    "@mongez/localization": "^3.4.7",
+    "@mongez/localization": "^3.5.0",
     "@mongez/supportive-is": "^2.1.4",
     "@warlock.js/auth": "0.0.0-set-by-scaffolder",
     "@warlock.js/cache": "0.0.0-set-by-scaffolder",

package/templates/warlock/skills/web-code-standards/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: web-code-standards
+description: >-
+  Strict separation-of-concerns standards for Warlock.js src/web pages and
+  components: loaders delegate data and business rules to app services;
+  components delegate all behavior to separate custom-hook files.
+  Use alongside code-standards for web work; skip for backend-only changes.
+---
+
+# Web code standards
+
+**Applies to:** `src/web/**` in this project. Read
+[`code-standards`](../code-standards/SKILL.md) for the shared TypeScript rules,
+and the relevant `@warlock.js/web` skill before using a framework feature.
+This skill adds the web-specific rules; it does not override security or
+module-boundary requirements. When reviewing existing code, identify debt
+without expanding a requested edit into a wholesale refactor.
+
+The bar is a page whose data flow and ownership a new teammate can explain
+without tracing a large component, several implicit casts, and unrelated
+network handlers. Good UI polish is not a substitute for that clarity.
+
+## Feature directories
+
+Keep files beside the web feature that owns them. For example, `src/web/posts/`
+can own an archive, article route, reader controls, comments, and their hooks
+and copy. `src/web/auth/` and `account/` own their flows; `src/web/admin/`
+can own a guarded dashboard and its domain features. Root document, root
+layout, error pages, home page, and shared site chrome stay at their common
+ancestor.
+
+When moving a page, check whether its URL is filesystem-derived. If it is,
+moving the file changes the URL unless you first give `config` an explicit
+`route`. Preserve any explicit `config.route.path` and `config.route.name`,
+and keep protected pages under the layout that owns their server auth guard.
+Place `locales.json` dictionaries with the feature they describe; site copy
+belongs at the common physical source ancestor and admin-only copy belongs
+under the admin layout. Warlock discovers these dictionaries automatically
+and supplies the selected locale through request translation helpers and
+`useTrans()`. An optional nonempty `$group` replaces the inferred static
+directory namespace. Every flattened translation key must have one owner;
+ancestor and child dictionaries cannot redefine the same key. Keep legacy
+`register()` dictionaries only where global translations are still needed.
+
+## 1. Keep the page contract, make the implementation thin
+
+Warlock's file-routed modules have one policy export: `config`. A page's
+`route`, `cache`, `middleware`, `validation`, `metadata`, and `sitemap` all
+belong in that object; do not use legacy top-level policy exports. `loader`,
+`register`, `ErrorBoundary`, and the default component remain top-level
+exports. Layouts, registration files, `root.tsx`, `404.page.tsx`, and
+`error.page.tsx` also have framework-defined roles. These are intentional
+exceptions to the generic "one primary export per file" rule; do not split
+them merely to satisfy it.
+
+Use the config type that matches the module. A page can preserve loader data
+inference for metadata by satisfying `PageConfig<typeof loader>`:
+
+```tsx
+import type { PageConfig } from "@warlock.js/web";
+
+export async function loader() {
+  return { title: "Posts" };
+}
+
+export const config = {
+  route: { path: "/posts", name: "posts.index" },
+  middleware: [requireUser],
+  validation: { query: postsQuery },
+  metadata: ({ data }) => ({ title: data.title }),
+  sitemap: { changefreq: "daily" },
+} satisfies PageConfig<typeof loader>;
+
+export default function PostsPage() {
+  return <main>Posts</main>;
+}
+```
+
+When code navigates by a page name, `href(name, params, query)` validates the
+published route table at runtime. `href("posts.indxe")` is a string that
+TypeScript accepts, then the helper throws with the known route names. Generated
+route-name and parameter types are not available in 5.17.
+
+Layouts use one `config satisfies LayoutConfig` object for `prefix`,
+`middleware`, `metadata`, and a sitemap default. Roots use one
+`config satisfies RootConfig` object for `middleware` and the static `strictMode`
+flag: root modules do
+not declare routes, prefixes, metadata, validation, cache, or sitemap policy.
+
+```tsx
+import type { LayoutConfig, RootConfig } from "@warlock.js/web";
+
+// src/web/account/layout.tsx
+export const config = {
+  prefix: "/account",
+  middleware: [requireUser],
+  metadata: { robots: "noindex" },
+  sitemap: false,
+} satisfies LayoutConfig;
+
+// src/web/root.tsx
+export const config = {
+  middleware: [loadRequestContext],
+} satisfies RootConfig;
+```
+
+A page file declares its route contract, coordinates a controller-like loader,
+and composes presentational components. The loader validates input, calls
+named services under `src/app/<domain>/services/`, converts results through
+their resources, and returns the page data. **Every model/repository read and
+every business rule belongs in an app service, even when the loader would need
+only one query.** Do not import models or repositories into page or layout
+loaders. Keep service orchestration in the loader; keep business decisions,
+queries, aggregations, and domain transformations in the service. A service
+must have a meaningful domain name and own the operation, not exist as a
+generic pass-through for a repository method.
+
+Extract substantive view sections into cohesive components. A component
+that needs any behavior gets a separate feature-named custom-hook file; a
+component with no behavior stays presentational and needs no hook. Split by
+responsibility, not by a mechanical line-count limit. Framework exports
+remain in the page file even when their work is delegated elsewhere.
+
+Preserve the framework's rendering boundary: `root.tsx` owns the document,
+`#vessel` and `<Scripts />`; the loader runs on the server, while the rendered
+component can run on the server **and** the client. Do not move request,
+database, or secret access into a component or hook. If page-only exports
+need server dependencies, use them only in server-side exports and follow the
+web skill's import-graph rules. A new auth gate belongs in server middleware,
+not a hidden link or a client-side redirect.
+
+**Example split:** a post page's loader passes validated input to
+`app/posts/services/get-public-post.service.ts` and returns its resource
+output; the page composes `PostArticle`, `PostComments`, and `RelatedPosts`;
+`use-post-comments.ts` owns subscription, state, and handlers for
+`PostComments`. Each piece has one reason to change.
+
+## 2. Make the server-to-browser data contract explicit
+
+- Validate URL parameters and query input at the page boundary. Use the
+  framework's validated request rather than `request.input()` casts where
+  validation is available. A `page` parameter must affect a real bounded
+  query; accepting and returning it without paging is misleading.
+- Have the app service query only what the view needs. Filter, sort, limit,
+  and paginate in the data source **before** serialization or rendering. Use
+  a count/aggregate query for totals instead of loading a table to count it.
+  Batch related reads; do not do one author lookup or image transformation
+  per row on an archive page. Cache does not make an unbounded cold path safe.
+- Treat resources as the wire-format gate. Send the resource's deliberate
+  public shape, never a raw model, secret field, or request object to the
+  browser. Do not scatter `toJSON() as unknown as SomeRow` through pages:
+  fix or explicitly validate the resource contract at a single boundary so
+  refactors cannot silently invalidate loader data.
+- Publicly cached pages must not contain viewer-specific state. Keep optional
+  identity in an appropriate request-scoped boundary and review cache keys,
+  invalidation, and private-page behaviour when the rendered data changes.
+- A deferred key needs a meaningful loading state and an error boundary at
+  the consuming section. Keep essential page data non-deferred. Do not wrap
+  already-resolved markup in more Suspense boundaries merely to appear
+  optimized; measure a real hydration or streaming benefit first.
+- Metadata, canonical links, and sitemap entries should derive from the
+  same validated, public data as the page. Keep private routes out of public
+  discovery, and do not generate database-backed assets on every GET.
+
+## 3. Components render; custom hooks own all behavior
+
+**No behavior in React component bodies, even when it is small.** A
+component may declare props, call its dedicated custom hook if needed,
+and render JSX from its props and the hook's returned values. Put `useState`,
+`useEffect`, subscriptions, timers, browser API calls, derived-value
+calculations, event handlers, mutations, and navigation decisions in a
+separate custom-hook file. Keep pure domain calculations in `src/app`
+services; a hook may call a small pure UI helper outside the component.
+Do not put a one-line callback or inline computation in JSX because it
+"doesn't warrant a hook". Pure presentational components need no hook.
+JSX conditionals that only select which markup to show are presentation,
+not a license to implement business rules in render.
+
+Render must be deterministic for the same props and request data. Read
+`window`, `document`, `localStorage`, browser clocks, and capabilities in
+hook handlers or effects, not during server rendering or initial hydration.
+Use request-provided data for the first client frame; do not silently render
+another value and hope hydration reconciles it.
+
+Identify the source of truth for each value. Loader data is server truth;
+hook state is for an interaction or an intentional optimistic change.
+Avoid copying props into hook state without a plan for refresh and client
+navigation. Avoid setting another state variable inside a state-updater
+callback. Prefer deriving display values from one authoritative state.
+
+Effects own their subscriptions and timers: unsubscribe, cancel, or ignore
+stale async work on unmount or entity change. A failed script/socket load
+must not leave a permanently rejected shared promise or silently disable a
+feature for the rest of the session. Realtime events can arrive twice or
+out of order; dedupe by stable identity and reconcile with refreshed data.
+
+## 4. Keep mutations and forms cohesive
+
+Client mutations belong in the feature's custom hook, **never inside the
+component or its JSX callback**. The hook owns the path from input to API
+request to success/error state to refresh or navigation. App services own
+the operation's business rules; the browser must not reimplement them.
+Never assume an HTTP promise cannot reject. Do not swallow a failed mutation
+or network subscription; show actionable UI feedback and log at the
+appropriate boundary without leaking user data.
+
+Share a create/edit form's fields, request encoding, and validation-error
+mapping when they are the same contract. Keep differences explicit (such as
+required-on-create image versus optional-on-edit). Do not build a generic
+form engine for one pair of pages. Use typed request and response shapes;
+`unknown` is for a genuine boundary and must be narrowed before use.
+
+Keep secrets and access tokens out of browser storage. Client affordances
+are not authorization; protected page loaders and mutation endpoints must
+enforce the same policy independently. Use a full navigation when an auth or
+document boundary requires it, otherwise prefer the framework's navigation
+and refresh primitives so state and loader data stay in sync.
+
+## 5. Ship usable, localizable presentation
+
+- Use semantic landmarks, headings, buttons, links, and explicit form labels.
+  A placeholder is not a label. Put validation feedback next to its input;
+  announce asynchronous success and failure accessibly. Preserve visible
+  keyboard focus, reduced-motion preferences, and useful empty/loading/
+  failure states.
+- Reuse design tokens and cohesive feature components. Keep utility classes
+  readable; extract repeated semantics or interactions, not an abstraction
+  for every repeated class string.
+- If the UI offers a language switch, translate first-party visible copy,
+  metadata, and accessible names for supported locales. User-generated
+  content can remain in its original language. Do not claim a locale is
+  complete when only the navigation is translated.
+- Comments explain non-obvious constraints or measured tradeoffs. They do not
+  narrate ordinary JSX or promise performance gains without evidence.
+  Remove stale starter examples and unexplained debugging writes before
+  shipping.
+
+## 6. Review and enforcement
+
+Apply the shared `code-standards` rules to web TypeScript as well: `type` for
+plain props/data, no `any`, no swallowed catches, no unsafe assertions used
+to hide an unknown data contract. Configure non-mutating ESLint and formatting
+checks to enforce rules that can be automated; do not rely on a lint command
+that rewrites files as the only quality gate.
+
+When tests are enabled, cover high-value behaviour through the public page
+and component contracts: server render and hydration, pagination/filtering,
+auth and error boundaries, form success/failure, navigation refresh, and
+realtime cleanup. Co-locate focused tests per the testing-strategy skill.
+Review accessibility and locale behavior in the actual supported modes.
+
+Before approving a web change, ask:
+
+1. Can a reader identify the page's server data, browser state, and side
+   effects without untangling unrelated responsibilities?
+2. Does every loader obtain data and business decisions from a named app
+   service, with models/repositories kept out of the web layer?
+3. Does each behavioral component delegate all state, effects, derived
+   values, event handlers, and mutations to its own custom hook file?
+4. Is the service query bounded, the resource shape intentional, and the
+   cache scope safe?
+5. Do refresh, navigation, errors, retries, and cleanup leave the UI correct?
+6. Are forms and interactions accessible and translated to the degree the
+   interface promises?
+7. Are the relevant quality rules enforced or covered by focused tests,
+   rather than described only in comments?

package/templates/warlock/src/app/uploads/routes.ts

@@ -1,4 +1,8 @@
-import { router } from "@warlock.js/core";
-import { fetchUploadedFileController } from "./controllers/fetch-uploaded-file.controller";
+import { router, uploadedFileController } from "@warlock.js/core";
 
-router.get("/uploads/*", fetchUploadedFileController);
+/**
+ * Serves local uploads. Image variants are opt-in and bounded: only the names
+ * declared in `uploads.images.variants` can be requested, e.g.
+ * `/uploads/avatars/me.jpg?variant=thumb&format=webp`.
+ */
+router.get("/uploads/*", uploadedFileController);

package/templates/warlock/src/config/cache.ts

@@ -5,39 +5,37 @@ import {
   RedisCacheDriver,
   type CacheConfigurations,
 } from "@warlock.js/cache";
-import { DatabaseCacheDriver, env, useRequestStore } from "@warlock.js/core";
+import { DatabaseCacheDriver, env } from "@warlock.js/core";
 
 /**
- * Namespace every cache key by the caller's domain, so two tenants hitting the
- * same app never read each other's cached values.
+ * Namespace every cache key by this app, fixed at boot.
  *
- * This used to branch on `request.client` first. That property does not exist:
- * it survived from v4, where `Request` carried a `[key: string]: any` index
- * signature that made any property name compile. v5 removed the index signature
- * and the branch became a type error.
+ * This used to derive the prefix from `request.originDomain` / the `domain`
+ * header / `?domain=` input. That broke two ways at once: a browser GET has
+ * no `Origin` while a CSRF-protected POST does, so the two resolved to
+ * different prefixes and a write could never invalidate what a read had
+ * cached — repository caches and page-cache tags went silently stale. Worse,
+ * none of those three inputs are server-validated, so any visitor could pick
+ * `?domain=anything` and grow the store under an arbitrary namespace forever.
  *
- * It was deleted rather than renamed. The obvious "fix" — pointing it at
- * `request.locals.client` — compiles and is worse than the bug: nothing in the
- * framework populates `request.locals`, so the branch would be permanently
- * `undefined` and silently dead. `originDomain` below is real (it is derived
- * from the `Origin` header) and already covers the multi-tenant case, so the
- * scaffold prefixes on that and models nothing the framework does not provide.
+ * A cache prefix has to come from something the app decides, not something
+ * a request carries.
  */
-const globalPrefix = () => {
-  const { request } = useRequestStore();
+const globalPrefix = () => env("APP_NAME", "store");
 
-  let cachePrefix = "store";
-
-  if (!request) return cachePrefix;
-
-  const domain = request.originDomain || request.header("domain") || request.input("domain");
-
-  if (!domain) return cachePrefix;
-
-  cachePrefix = `${cachePrefix}.${domain}`;
-
-  return cachePrefix;
-};
+/**
+ * Genuine multi-tenancy (one deployment, many tenants, isolated caches) needs
+ * a tenant id the app has already validated server-side — e.g. set on
+ * `request.locals.tenant` by the app's own tenant middleware after resolving
+ * the host against its tenants table — never the raw `Origin`/`Host`, a
+ * header, or query input, none of which the framework trusts.
+ *
+ * const globalPrefix = () => {
+ *   const { request } = useRequestStore();
+ *   const tenant = request?.locals.tenant; // set by app tenant middleware, already validated
+ *   return tenant ? `${env("APP_NAME", "store")}.${tenant}` : env("APP_NAME", "store");
+ * };
+ */
 
 const cacheConfigurations: CacheConfigurations<"database"> = {
   // Driven by CACHE_DRIVER so the shipped .env (`memory`) actually wins.

package/templates/warlock/src/config/http.ts

@@ -18,6 +18,23 @@ const httpConfigurations: HttpConfigurations = {
     // allowed methods
     methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
   },
+  // Safe for local dev: `false` trusts nothing in front of this process, so
+  // request.ip/protocol/hostname read the raw socket. Behind a proxy/LB/CDN
+  // in production, set this to `true`, a trusted IP/CIDR string, or a list
+  // of trusted proxy IPs/CIDRs — otherwise rate limiting, ip-filter
+  // allowlists, and absolute URLs (e.g. the sitemap) trust the wrong client.
+  trustProxy: false,
+  // Opt-in, nonce-based Content-Security-Policy — off by default, zero
+  // behaviour change. Flip `enabled: true` to turn it on; the framework
+  // appends the request's own `'nonce-<value>'` to `script-src` for you.
+  // csp: {
+  //   enabled: false,
+  //   directives: {
+  //     "script-src": ["'self'"],
+  //     "object-src": ["'none'"],
+  //     "base-uri": ["'self'"],
+  //   },
+  // },
 };
 
 export default httpConfigurations;