@warlock.js/core 5.1.0 → 5.2.1

package/esm/generations/features/shared/migration-timestamp.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration-timestamp.mjs","names":[],"sources":["../../../../../../../../../core/src/generations/features/shared/migration-timestamp.ts"],"sourcesContent":["/**\n * Build a migration filename timestamp prefix in the framework's\n * MM-DD-YYYY_HH-MM-SS form. Cascade infers a migration's createdAt from this\n * prefix and orders migrations deterministically by it. Pass `offsetSeconds` to\n * stamp sibling migrations created in the same scaffold a second apart so they\n * never collide and keep a stable relative order.\n */\nexport function migrationTimestamp(offsetSeconds = 0): string {\n  const now = new Date(Date.now() + offsetSeconds * 1000);\n  const pad = (value: number) => String(value).padStart(2, \"0\");\n\n  return (\n    `${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${now.getFullYear()}_` +\n    `${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`\n  );\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,mBAAmB,gBAAgB,GAAW;CAC5D,MAAM,MAAM,IAAI,KAAK,KAAK,IAAI,IAAI,gBAAgB,GAAI;CACtD,MAAM,OAAO,UAAkB,OAAO,KAAK,CAAC,CAAC,SAAS,GAAG,GAAG;CAE5D,OACE,GAAG,IAAI,IAAI,SAAS,IAAI,CAAC,EAAE,GAAG,IAAI,IAAI,QAAQ,CAAC,EAAE,GAAG,IAAI,YAAY,EAAE,GACnE,IAAI,IAAI,SAAS,CAAC,EAAE,GAAG,IAAI,IAAI,WAAW,CAAC,EAAE,GAAG,IAAI,IAAI,WAAW,CAAC;AAE3E"}
+{"version":3,"file":"migration-timestamp.mjs","names":[],"sources":["../../../../../../../../../core/src/generations/features/shared/migration-timestamp.ts"],"sourcesContent":["/**\n * Build a migration filename timestamp prefix in the framework's\n * MM-DD-YYYY_HH-MM-SS form. Cascade infers a migration's createdAt from this\n * prefix and orders migrations deterministically by it. Pass `offsetSeconds` to\n * stamp sibling migrations created in the same scaffold a second apart so they\n * never collide and keep a stable relative order.\n */\nexport function migrationTimestamp(offsetSeconds = 0): string {\n  const now = new Date(Date.now() + offsetSeconds * 1000);\n  const pad = (value: number) => String(value).padStart(2, \"0\");\n\n  return (\n    `${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${now.getFullYear()}_` +\n    `${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`\n  );\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,mBAAmB,gBAAgB,GAAW;CAC5D,MAAM,MAAM,IAAI,KAAK,KAAK,IAAI,IAAI,gBAAgB,GAAI;CACtD,MAAM,OAAO,UAAkB,OAAO,KAAK,EAAE,SAAS,GAAG,GAAG;CAE5D,OACE,GAAG,IAAI,IAAI,SAAS,IAAI,CAAC,EAAE,GAAG,IAAI,IAAI,QAAQ,CAAC,EAAE,GAAG,IAAI,YAAY,EAAE,GACnE,IAAI,IAAI,SAAS,CAAC,EAAE,GAAG,IAAI,IAAI,WAAW,CAAC,EAAE,GAAG,IAAI,IAAI,WAAW,CAAC;AAE3E"}

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

@@ -1 +1 @@
-{"version":3,"file":"tailwind.feature.mjs","names":[],"sources":["../../../../../../../../core/src/generations/features/tailwind.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport {\n  ensureDirectoryAsync,\n  fileExistsAsync,\n  getFileAsync,\n  putFileAsync,\n} from \"@warlock.js/fs\";\nimport { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport { FeatureDefinition } from \"./types\";\n\n/**\n * The stylesheet entry, and the whole of Tailwind's configuration.\n *\n * Tailwind v4 is CSS-first: there is no `tailwind.config.js` and no `content`\n * globs to keep in sync with the project layout — the engine discovers the\n * templates that reach it through the bundler graph, and everything a v3 config\n * held (`theme`, `plugins`, `darkMode`) is expressed in CSS beside the import.\n * So this one file is the config, which is why the feature writes it rather\n * than an `ejectConfig` entry: `ejectConfig` lands in `src/config/*.ts`, and a\n * stylesheet that must sit in the bundler's path does not belong there.\n */\nconst appCssStub = `@import \"tailwindcss\";\n\n/*\n  Tailwind v4 configures itself from CSS — there is no tailwind.config.js.\n\n  Design tokens go in an @theme block, and each one becomes both a CSS variable\n  and a utility class:\n\n    @theme {\n      --color-brand: oklch(0.62 0.19 259);\n      --font-display: \"Inter\", sans-serif;\n    }\n\n  gives you \\`bg-brand\\`, \\`text-brand\\`, \\`font-display\\` and \\`var(--color-brand)\\`.\n\n  Plugins are imported here too — \\`@plugin \"@tailwindcss/typography\";\\` — and\n  your own non-utility CSS can simply follow this comment.\n*/\n`;\n\n/**\n * PostCSS rather than a Vite config file, and deliberately at the project root.\n *\n * Vite discovers `postcss.config.mjs` from the project root on its own, in the\n * dev server and in `vite build` alike, without the application owning a Vite\n * config at all. That matters here: the only app-facing Vite plugin array in\n * this framework is `webConnector({ plugins })`, which is wired into the DEV\n * server exclusively — the client build composes its own plugin list from its\n * caller. Registering `@tailwindcss/vite` there would produce styles in `dev`\n * and silently drop them from a production build, which is a worse failure than\n * any config file, because it only shows up after deploy.\n *\n * `.mjs` because a Warlock project's `package.json` is not guaranteed to set\n * `\"type\": \"module\"`, and `export default` in a `.js` file would throw in a\n * CommonJS project.\n */\nconst postcssConfigStub = `/**\n * Tailwind v4 runs as a PostCSS plugin. Vite loads this file automatically —\n * in dev and in build — so no Vite configuration is required.\n *\n * The plugin lives in its own package in v4: \\`tailwindcss\\` is the engine,\n * \\`@tailwindcss/postcss\\` is the adapter. Naming \\`tailwindcss\\` here directly is\n * the v3 spelling and will not work.\n */\nexport default {\n  plugins: {\n    \"@tailwindcss/postcss\": {},\n  },\n};\n`;\n\n/**\n * Every filename Vite/PostCSS will pick up from the project root.\n *\n * Checked as a set rather than just writing our own: two PostCSS configs in one\n * directory is not a merge, it is a coin toss over which one loads, so a project\n * that already has one gets instructions instead of a second file.\n */\nconst POSTCSS_CONFIG_FILES = [\n  \"postcss.config.mjs\",\n  \"postcss.config.js\",\n  \"postcss.config.cjs\",\n  \"postcss.config.ts\",\n  \"postcss.config.json\",\n  \".postcssrc\",\n  \".postcssrc.js\",\n  \".postcssrc.json\",\n];\n\n/** The side-effect import that pulls the stylesheet into the bundler graph. */\nconst APP_CSS_IMPORT = 'import \"./app.css\";';\n\n/**\n * Create `src/web/app.css` — the sentinel for \"this feature already ran\".\n *\n * Nothing in the project template creates this file (the scaffold ships a\n * static `public/home.css` instead), so its presence means `add tailwind` has\n * been here, and its contents may since have been edited into a real design\n * system. It is never rewritten.\n */\nasync function createStylesheet(): Promise<boolean> {\n  const cssFile = srcPath(\"web/app.css\");\n\n  if (await fileExistsAsync(cssFile)) {\n    console.log(`${colors.yellowBright(\"src/web/app.css\")} already exists, skipping...`);\n\n    return false;\n  }\n\n  await ensureDirectoryAsync(srcPath(\"web\"));\n  await putFileAsync(cssFile, appCssStub);\n  console.log(`${colors.green(\"✓\")} Created src/web/app.css`);\n\n  return true;\n}\n\n/**\n * Write `postcss.config.mjs`, unless the project already has a PostCSS config.\n *\n * An existing config is left completely alone. It is an app-owned build file\n * that may already register autoprefixer, nesting, or a CSS-modules pass, and\n * appending Tailwind to it by string surgery would be guessing at both its\n * module format and its plugin order.\n */\nasync function writePostcssConfig(): Promise<void> {\n  for (const name of POSTCSS_CONFIG_FILES) {\n    if (!(await fileExistsAsync(rootPath(name)))) continue;\n\n    const current = await getFileAsync(rootPath(name)).catch(() => \"\");\n\n    if (current.includes(\"@tailwindcss/postcss\")) {\n      console.log(`${colors.yellowBright(name)} already registers Tailwind, skipping...`);\n    } else {\n      console.log(\n        `${colors.yellowBright(\"!\")} ${colors.yellowBright(name)} already exists — add Tailwind to it yourself:\\n` +\n          `  plugins: { \"@tailwindcss/postcss\": {} }\\n` +\n          \"  Two PostCSS configs in one project is undefined behaviour, so this feature did not write a second one.\",\n      );\n    }\n\n    return;\n  }\n\n  await putFileAsync(rootPath(\"postcss.config.mjs\"), postcssConfigStub);\n  console.log(`${colors.green(\"✓\")} Created postcss.config.mjs`);\n}\n\n/**\n * Import the stylesheet from `src/web/root.tsx`.\n *\n * The root is the one module every SSR page renders through, so importing the\n * stylesheet there is what puts it in the client bundle for every route.\n *\n * `root.tsx` is guaranteed to exist by the time this runs: `requires: [\"web\"]`\n * makes the add command resolve `web` ahead of `tailwind` and run its\n * `onExecuting` first, and that is what creates the file. The check below is\n * therefore for a root a human has since moved or deleted — a case worth a\n * printed instruction, not a failure.\n */\nasync function importStylesheetFromRoot(): Promise<void> {\n  const rootFile = srcPath(\"web/root.tsx\");\n\n  if (!(await fileExistsAsync(rootFile))) {\n    console.log(\n      `${colors.yellowBright(\"!\")} ${colors.yellowBright(\"src/web/root.tsx\")} not found — ` +\n        `add ${colors.yellowBright(APP_CSS_IMPORT)} to your application root yourself.\\n` +\n        \"  Until the stylesheet is imported from a module the bundler reaches, no Tailwind CSS is emitted.\",\n    );\n\n    return;\n  }\n\n  const current = await getFileAsync(rootFile);\n\n  // Matches the import whichever quote style and specifier the file uses, so a\n  // re-run against a hand-edited root does not stack a second copy.\n  if (/import\\s+[\"'].*app\\.css[\"']/.test(current)) {\n    console.log(`${colors.yellowBright(\"src/web/root.tsx\")} already imports app.css, skipping...`);\n\n    return;\n  }\n\n  // FIRST line, above the framework imports. A side-effect CSS import has no\n  // binding to order against, and putting it at the top keeps it from being\n  // swept away by an import sorter that only ranks module specifiers.\n  await putFileAsync(rootFile, `${APP_CSS_IMPORT}\\n${current}`);\n  console.log(`${colors.green(\"✓\")} Imported app.css in src/web/root.tsx`);\n}\n\n/**\n * Wire Tailwind v4 into the page layer.\n *\n * Three files, none of which needs `node_modules` to be populated: on the\n * `create-warlock` path this runs under `--no-install`, so the dependencies\n * declared below are only recorded in `package.json` and nothing here may\n * import, resolve, or execute Tailwind itself.\n */\nasync function completeTailwindInstallation(_options: CommandActionData) {\n  await createStylesheet();\n  await writePostcssConfig();\n  await importStylesheetFromRoot();\n}\n\nexport const tailwindFeature: FeatureDefinition = {\n  description:\n    \"Installs Tailwind CSS v4 for the SSR page layer. Creates src/web/app.css (the CSS-first config — v4 has no tailwind.config.js), imports it from src/web/root.tsx, and registers the engine through postcss.config.mjs, which Vite loads in dev and build alike.\",\n  // `web` owns root.tsx and the CSS pipeline that serves this stylesheet.\n  // Requiring it also fixes the order: the add command resolves requirements\n  // depth-first, so `web` scaffolds src/web before this feature writes into it.\n  requires: [\"web\"],\n  devDependencies: {\n    // Build-time only, both of them — Tailwind compiles to a plain stylesheet\n    // and nothing it ships is imported at runtime.\n    tailwindcss: \"^4.1.16\",\n    // The engine and its PostCSS adapter are separate packages in v4 and are\n    // released in lockstep; keep these two ranges identical.\n    \"@tailwindcss/postcss\": \"^4.1.16\",\n  },\n  onExecuting: completeTailwindInstallation,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AAsBA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCnB,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;AAsB1B,MAAM,uBAAuB;CAC3B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAM,iBAAiB;;;;;;;;;AAUvB,eAAe,mBAAqC;CAClD,MAAM,UAAU,QAAQ,aAAa;CAErC,IAAI,MAAM,gBAAgB,OAAO,GAAG;EAClC,QAAQ,IAAI,GAAG,OAAO,aAAa,iBAAiB,EAAE,6BAA6B;EAEnF,OAAO;CACT;CAEA,MAAM,qBAAqB,QAAQ,KAAK,CAAC;CACzC,MAAM,aAAa,SAAS,UAAU;CACtC,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,yBAAyB;CAE1D,OAAO;AACT;;;;;;;;;AAUA,eAAe,qBAAoC;CACjD,KAAK,MAAM,QAAQ,sBAAsB;EACvC,IAAI,CAAE,MAAM,gBAAgB,SAAS,IAAI,CAAC,GAAI;EAI9C,KAAI,MAFkB,aAAa,SAAS,IAAI,CAAC,CAAC,CAAC,YAAY,EAAE,EAEtD,CAAC,SAAS,sBAAsB,GACzC,QAAQ,IAAI,GAAG,OAAO,aAAa,IAAI,EAAE,yCAAyC;OAElF,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,GAAG,OAAO,aAAa,IAAI,EAAE,oMAG3D;EAGF;CACF;CAEA,MAAM,aAAa,SAAS,oBAAoB,GAAG,iBAAiB;CACpE,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,4BAA4B;AAC/D;;;;;;;;;;;;;AAcA,eAAe,2BAA0C;CACvD,MAAM,WAAW,QAAQ,cAAc;CAEvC,IAAI,CAAE,MAAM,gBAAgB,QAAQ,GAAI;EACtC,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,GAAG,OAAO,aAAa,kBAAkB,EAAE,mBAC9D,OAAO,aAAa,cAAc,EAAE,uIAE/C;EAEA;CACF;CAEA,MAAM,UAAU,MAAM,aAAa,QAAQ;CAI3C,IAAI,8BAA8B,KAAK,OAAO,GAAG;EAC/C,QAAQ,IAAI,GAAG,OAAO,aAAa,kBAAkB,EAAE,sCAAsC;EAE7F;CACF;CAKA,MAAM,aAAa,UAAU,GAAG,eAAe,IAAI,SAAS;CAC5D,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,sCAAsC;AACzE;;;;;;;;;AAUA,eAAe,6BAA6B,UAA6B;CACvE,MAAM,iBAAiB;CACvB,MAAM,mBAAmB;CACzB,MAAM,yBAAyB;AACjC;AAEA,MAAa,kBAAqC;CAChD,aACE;CAIF,UAAU,CAAC,KAAK;CAChB,iBAAiB;EAGf,aAAa;EAGb,wBAAwB;CAC1B;CACA,aAAa;AACf"}
+{"version":3,"file":"tailwind.feature.mjs","names":[],"sources":["../../../../../../../../core/src/generations/features/tailwind.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport {\n  ensureDirectoryAsync,\n  fileExistsAsync,\n  getFileAsync,\n  putFileAsync,\n} from \"@warlock.js/fs\";\nimport { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport { FeatureDefinition } from \"./types\";\n\n/**\n * The stylesheet entry, and the whole of Tailwind's configuration.\n *\n * Tailwind v4 is CSS-first: there is no `tailwind.config.js` and no `content`\n * globs to keep in sync with the project layout — the engine discovers the\n * templates that reach it through the bundler graph, and everything a v3 config\n * held (`theme`, `plugins`, `darkMode`) is expressed in CSS beside the import.\n * So this one file is the config, which is why the feature writes it rather\n * than an `ejectConfig` entry: `ejectConfig` lands in `src/config/*.ts`, and a\n * stylesheet that must sit in the bundler's path does not belong there.\n */\nconst appCssStub = `@import \"tailwindcss\";\n\n/*\n  Tailwind v4 configures itself from CSS — there is no tailwind.config.js.\n\n  Design tokens go in an @theme block, and each one becomes both a CSS variable\n  and a utility class:\n\n    @theme {\n      --color-brand: oklch(0.62 0.19 259);\n      --font-display: \"Inter\", sans-serif;\n    }\n\n  gives you \\`bg-brand\\`, \\`text-brand\\`, \\`font-display\\` and \\`var(--color-brand)\\`.\n\n  Plugins are imported here too — \\`@plugin \"@tailwindcss/typography\";\\` — and\n  your own non-utility CSS can simply follow this comment.\n*/\n`;\n\n/**\n * PostCSS rather than a Vite config file, and deliberately at the project root.\n *\n * Vite discovers `postcss.config.mjs` from the project root on its own, in the\n * dev server and in `vite build` alike, without the application owning a Vite\n * config at all. That matters here: the only app-facing Vite plugin array in\n * this framework is `webConnector({ plugins })`, which is wired into the DEV\n * server exclusively — the client build composes its own plugin list from its\n * caller. Registering `@tailwindcss/vite` there would produce styles in `dev`\n * and silently drop them from a production build, which is a worse failure than\n * any config file, because it only shows up after deploy.\n *\n * `.mjs` because a Warlock project's `package.json` is not guaranteed to set\n * `\"type\": \"module\"`, and `export default` in a `.js` file would throw in a\n * CommonJS project.\n */\nconst postcssConfigStub = `/**\n * Tailwind v4 runs as a PostCSS plugin. Vite loads this file automatically —\n * in dev and in build — so no Vite configuration is required.\n *\n * The plugin lives in its own package in v4: \\`tailwindcss\\` is the engine,\n * \\`@tailwindcss/postcss\\` is the adapter. Naming \\`tailwindcss\\` here directly is\n * the v3 spelling and will not work.\n */\nexport default {\n  plugins: {\n    \"@tailwindcss/postcss\": {},\n  },\n};\n`;\n\n/**\n * Every filename Vite/PostCSS will pick up from the project root.\n *\n * Checked as a set rather than just writing our own: two PostCSS configs in one\n * directory is not a merge, it is a coin toss over which one loads, so a project\n * that already has one gets instructions instead of a second file.\n */\nconst POSTCSS_CONFIG_FILES = [\n  \"postcss.config.mjs\",\n  \"postcss.config.js\",\n  \"postcss.config.cjs\",\n  \"postcss.config.ts\",\n  \"postcss.config.json\",\n  \".postcssrc\",\n  \".postcssrc.js\",\n  \".postcssrc.json\",\n];\n\n/** The side-effect import that pulls the stylesheet into the bundler graph. */\nconst APP_CSS_IMPORT = 'import \"./app.css\";';\n\n/**\n * Create `src/web/app.css` — the sentinel for \"this feature already ran\".\n *\n * Nothing in the project template creates this file (the scaffold ships a\n * static `public/home.css` instead), so its presence means `add tailwind` has\n * been here, and its contents may since have been edited into a real design\n * system. It is never rewritten.\n */\nasync function createStylesheet(): Promise<boolean> {\n  const cssFile = srcPath(\"web/app.css\");\n\n  if (await fileExistsAsync(cssFile)) {\n    console.log(`${colors.yellowBright(\"src/web/app.css\")} already exists, skipping...`);\n\n    return false;\n  }\n\n  await ensureDirectoryAsync(srcPath(\"web\"));\n  await putFileAsync(cssFile, appCssStub);\n  console.log(`${colors.green(\"✓\")} Created src/web/app.css`);\n\n  return true;\n}\n\n/**\n * Write `postcss.config.mjs`, unless the project already has a PostCSS config.\n *\n * An existing config is left completely alone. It is an app-owned build file\n * that may already register autoprefixer, nesting, or a CSS-modules pass, and\n * appending Tailwind to it by string surgery would be guessing at both its\n * module format and its plugin order.\n */\nasync function writePostcssConfig(): Promise<void> {\n  for (const name of POSTCSS_CONFIG_FILES) {\n    if (!(await fileExistsAsync(rootPath(name)))) continue;\n\n    const current = await getFileAsync(rootPath(name)).catch(() => \"\");\n\n    if (current.includes(\"@tailwindcss/postcss\")) {\n      console.log(`${colors.yellowBright(name)} already registers Tailwind, skipping...`);\n    } else {\n      console.log(\n        `${colors.yellowBright(\"!\")} ${colors.yellowBright(name)} already exists — add Tailwind to it yourself:\\n` +\n          `  plugins: { \"@tailwindcss/postcss\": {} }\\n` +\n          \"  Two PostCSS configs in one project is undefined behaviour, so this feature did not write a second one.\",\n      );\n    }\n\n    return;\n  }\n\n  await putFileAsync(rootPath(\"postcss.config.mjs\"), postcssConfigStub);\n  console.log(`${colors.green(\"✓\")} Created postcss.config.mjs`);\n}\n\n/**\n * Import the stylesheet from `src/web/root.tsx`.\n *\n * The root is the one module every SSR page renders through, so importing the\n * stylesheet there is what puts it in the client bundle for every route.\n *\n * `root.tsx` is guaranteed to exist by the time this runs: `requires: [\"web\"]`\n * makes the add command resolve `web` ahead of `tailwind` and run its\n * `onExecuting` first, and that is what creates the file. The check below is\n * therefore for a root a human has since moved or deleted — a case worth a\n * printed instruction, not a failure.\n */\nasync function importStylesheetFromRoot(): Promise<void> {\n  const rootFile = srcPath(\"web/root.tsx\");\n\n  if (!(await fileExistsAsync(rootFile))) {\n    console.log(\n      `${colors.yellowBright(\"!\")} ${colors.yellowBright(\"src/web/root.tsx\")} not found — ` +\n        `add ${colors.yellowBright(APP_CSS_IMPORT)} to your application root yourself.\\n` +\n        \"  Until the stylesheet is imported from a module the bundler reaches, no Tailwind CSS is emitted.\",\n    );\n\n    return;\n  }\n\n  const current = await getFileAsync(rootFile);\n\n  // Matches the import whichever quote style and specifier the file uses, so a\n  // re-run against a hand-edited root does not stack a second copy.\n  if (/import\\s+[\"'].*app\\.css[\"']/.test(current)) {\n    console.log(`${colors.yellowBright(\"src/web/root.tsx\")} already imports app.css, skipping...`);\n\n    return;\n  }\n\n  // FIRST line, above the framework imports. A side-effect CSS import has no\n  // binding to order against, and putting it at the top keeps it from being\n  // swept away by an import sorter that only ranks module specifiers.\n  await putFileAsync(rootFile, `${APP_CSS_IMPORT}\\n${current}`);\n  console.log(`${colors.green(\"✓\")} Imported app.css in src/web/root.tsx`);\n}\n\n/**\n * Wire Tailwind v4 into the page layer.\n *\n * Three files, none of which needs `node_modules` to be populated: on the\n * `create-warlock` path this runs under `--no-install`, so the dependencies\n * declared below are only recorded in `package.json` and nothing here may\n * import, resolve, or execute Tailwind itself.\n */\nasync function completeTailwindInstallation(_options: CommandActionData) {\n  await createStylesheet();\n  await writePostcssConfig();\n  await importStylesheetFromRoot();\n}\n\nexport const tailwindFeature: FeatureDefinition = {\n  description:\n    \"Installs Tailwind CSS v4 for the SSR page layer. Creates src/web/app.css (the CSS-first config — v4 has no tailwind.config.js), imports it from src/web/root.tsx, and registers the engine through postcss.config.mjs, which Vite loads in dev and build alike.\",\n  // `web` owns root.tsx and the CSS pipeline that serves this stylesheet.\n  // Requiring it also fixes the order: the add command resolves requirements\n  // depth-first, so `web` scaffolds src/web before this feature writes into it.\n  requires: [\"web\"],\n  devDependencies: {\n    // Build-time only, both of them — Tailwind compiles to a plain stylesheet\n    // and nothing it ships is imported at runtime.\n    tailwindcss: \"^4.1.16\",\n    // The engine and its PostCSS adapter are separate packages in v4 and are\n    // released in lockstep; keep these two ranges identical.\n    \"@tailwindcss/postcss\": \"^4.1.16\",\n  },\n  onExecuting: completeTailwindInstallation,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AAsBA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCnB,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;AAsB1B,MAAM,uBAAuB;CAC3B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAM,iBAAiB;;;;;;;;;AAUvB,eAAe,mBAAqC;CAClD,MAAM,UAAU,QAAQ,aAAa;CAErC,IAAI,MAAM,gBAAgB,OAAO,GAAG;EAClC,QAAQ,IAAI,GAAG,OAAO,aAAa,iBAAiB,EAAE,6BAA6B;EAEnF,OAAO;CACT;CAEA,MAAM,qBAAqB,QAAQ,KAAK,CAAC;CACzC,MAAM,aAAa,SAAS,UAAU;CACtC,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,yBAAyB;CAE1D,OAAO;AACT;;;;;;;;;AAUA,eAAe,qBAAoC;CACjD,KAAK,MAAM,QAAQ,sBAAsB;EACvC,IAAI,CAAE,MAAM,gBAAgB,SAAS,IAAI,CAAC,GAAI;EAI9C,KAAI,MAFkB,aAAa,SAAS,IAAI,CAAC,EAAE,YAAY,EAAE,GAErD,SAAS,sBAAsB,GACzC,QAAQ,IAAI,GAAG,OAAO,aAAa,IAAI,EAAE,yCAAyC;OAElF,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,GAAG,OAAO,aAAa,IAAI,EAAE,oMAG3D;EAGF;CACF;CAEA,MAAM,aAAa,SAAS,oBAAoB,GAAG,iBAAiB;CACpE,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,4BAA4B;AAC/D;;;;;;;;;;;;;AAcA,eAAe,2BAA0C;CACvD,MAAM,WAAW,QAAQ,cAAc;CAEvC,IAAI,CAAE,MAAM,gBAAgB,QAAQ,GAAI;EACtC,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,GAAG,OAAO,aAAa,kBAAkB,EAAE,mBAC9D,OAAO,aAAa,cAAc,EAAE,uIAE/C;EAEA;CACF;CAEA,MAAM,UAAU,MAAM,aAAa,QAAQ;CAI3C,IAAI,8BAA8B,KAAK,OAAO,GAAG;EAC/C,QAAQ,IAAI,GAAG,OAAO,aAAa,kBAAkB,EAAE,sCAAsC;EAE7F;CACF;CAKA,MAAM,aAAa,UAAU,GAAG,eAAe,IAAI,SAAS;CAC5D,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,sCAAsC;AACzE;;;;;;;;;AAUA,eAAe,6BAA6B,UAA6B;CACvE,MAAM,iBAAiB;CACvB,MAAM,mBAAmB;CACzB,MAAM,yBAAyB;AACjC;AAEA,MAAa,kBAAqC;CAChD,aACE;CAIF,UAAU,CAAC,KAAK;CAChB,iBAAiB;EAGf,aAAa;EAGb,wBAAwB;CAC1B;CACA,aAAa;AACf"}

package/esm/generations/features/types.mjs

@@ -0,0 +1,14 @@
+//#region ../core/src/generations/features/types.ts
+/**
+* Internal placeholder for an @warlock.js dependency whose concrete version
+* comes from the installed Core package at command execution time.
+*
+* This is deliberately not a valid package-manager range. If a future code
+* path forgets to resolve it, installation fails loudly instead of silently
+* falling back to a stale framework major copied into a feature definition.
+*/
+const INSTALLED_WARLOCK_VERSION = "__INSTALLED_WARLOCK_VERSION__";
+
+//#endregion
+export { INSTALLED_WARLOCK_VERSION };
+//# sourceMappingURL=types.mjs.map

package/esm/generations/features/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../../../../../../core/src/generations/features/types.ts"],"sourcesContent":["import { CommandActionData } from \"../../commands/types\";\n\n/**\n * Internal placeholder for an @warlock.js dependency whose concrete version\n * comes from the installed Core package at command execution time.\n *\n * This is deliberately not a valid package-manager range. If a future code\n * path forgets to resolve it, installation fails loudly instead of silently\n * falling back to a stale framework major copied into a feature definition.\n */\nexport const INSTALLED_WARLOCK_VERSION = \"__INSTALLED_WARLOCK_VERSION__\";\n\r\n/**\r\n * One entry in the feature registry.\r\n *\r\n * Every feature owns a module of its own that exports a single value of this\r\n * shape, with its `onExecuting` body beside it; `features/index.ts` is only the\r\n * ordered index that collects them.\r\n */\r\nexport type FeatureDefinition = {\r\n  dependencies?: Record<string, string>;\r\n  devDependencies?: Record<string, string>;\r\n  description: string;\r\n  requires?: string[];\r\n  script?: Record<string, string>;\r\n  onExecuting?: (options: CommandActionData) => Promise<any>;\r\n  ejectConfig?: {\r\n    content: string;\r\n    name: string;\r\n  };\r\n};\r\n"],"mappings":";;;;;;;;;AAUA,MAAa,4BAA4B"}

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

@@ -1,6 +1,7 @@
 import { rootPath, srcPath } from "../../utils/paths.mjs";
 import "../../utils/index.mjs";
-import { webHomePageStub, webRootStub } from "../stubs.mjs";
+import { webContactControllerStub, webContactRoutesStub, webHomePageStub, webRootStub } from "../stubs.mjs";
+import { INSTALLED_WARLOCK_VERSION } from "./types.mjs";
 import { colors } from "@mongez/copper";
 import { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "@warlock.js/fs";
 
@@ -153,7 +154,11 @@ async function completeWebInstallation(_options) {
 			process.exitCode = 1;
 		} else {
 			await putFileAsync(srcPath("web/home.page.tsx"), webHomePageStub);
+			await ensureDirectoryAsync(srcPath("app/contact/controllers"));
+			await putFileAsync(srcPath("app/contact/controllers/contact.controller.ts"), webContactControllerStub);
+			await putFileAsync(srcPath("app/contact/routes.ts"), webContactRoutesStub);
 			console.log(`${colors.green("✓")} Created src/web/home.page.tsx`);
+			console.log(`${colors.green("✓")} Created POST /api/contact starter route`);
 		}
 	}
 	await registerWebConnector();
@@ -161,7 +166,10 @@ async function completeWebInstallation(_options) {
 const webFeature = {
 	description: "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.",
 	dependencies: {
-		"@warlock.js/web": "~4.0.0",
+		"@warlock.js/web": INSTALLED_WARLOCK_VERSION,
+		"@mongez/http": "^3.5.0",
+		"@mongez/react-form": "^4.0.0",
+		"@mongez/react-localization": "^3.4.7",
 		react: "^19.2.3",
 		"react-dom": "^19.2.3"
 	},

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

@@ -1 +1 @@
-{"version":3,"file":"web.feature.mjs","names":[],"sources":["../../../../../../../../core/src/generations/features/web.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\r\nimport {\r\n  ensureDirectoryAsync,\r\n  fileExistsAsync,\r\n  getFileAsync,\r\n  putFileAsync,\r\n} from \"@warlock.js/fs\";\r\nimport { CommandActionData } from \"../../commands/types\";\r\nimport { rootPath, srcPath } from \"../../utils\";\r\nimport { webHomePageStub, webRootStub } from \"../stubs\";\r\nimport { FeatureDefinition } from \"./types\";\r\n\r\n/**\r\n * Register the WebConnector in `warlock.config.ts`, and ONLY there.\r\n *\r\n * It belongs to the config array or to app code, never both. Both halves are\r\n * registered before app code loads — the CLI preloader in dev, the generated\r\n * entry in production — so also calling `connectorsManager.register(...)` in\r\n * `src/app/main.ts` boots the connector twice and installs every page route\r\n * twice. That surfaces at PRODUCTION boot as `Route name \"...\" is already\r\n * taken`, because pages and API routes share one route-name namespace.\r\n *\r\n * The config array is the half to prefer: `warlock build` reads the same array\r\n * to drain each connector's build contribution, so \"built for\" and \"boots with\"\r\n * cannot drift.\r\n *\r\n * String surgery rather than a TypeScript parse: `warlock.config.ts` is an\r\n * app-owned file that may carry any formatting, and a parse-and-print would\r\n * reformat the parts we did not come to change.\r\n */\r\nasync function registerWebConnector(): Promise<void> {\r\n  const configPath = rootPath(\"warlock.config.ts\");\r\n\r\n  if (!(await fileExistsAsync(configPath))) {\r\n    console.log(\r\n      `${colors.yellowBright(\"warlock.config.ts\")} not found — add this yourself:\\n` +\r\n        `  import { webConnector } from \"@warlock.js/web/connector\";\\n` +\r\n        `  export default defineConfig({ connectors: [webConnector()] });`,\r\n    );\r\n\r\n    return;\r\n  }\r\n\r\n  const current = await getFileAsync(configPath);\r\n\r\n  if (current.includes(\"webConnector\")) {\r\n    console.log(`${colors.yellowBright(\"webConnector\")} already registered, skipping...`);\r\n\r\n    return;\r\n  }\r\n\r\n  const importLine = 'import { webConnector } from \"@warlock.js/web/connector\";';\r\n  let next = current.includes(importLine) ? current : `${importLine}\\n${current}`;\r\n\r\n  // An existing `connectors: [` gains one entry; otherwise the key is added to\r\n  // the object `defineConfig` receives.\r\n  if (/connectors:\\s*\\[/.test(next)) {\r\n    next = next.replace(/connectors:\\s*\\[/, \"connectors: [webConnector(),\");\r\n  } else if (next.includes(\"defineConfig({\")) {\r\n    next = next.replace(\"defineConfig({\", \"defineConfig({\\n  connectors: [webConnector()],\");\r\n  } else {\r\n    console.log(\r\n      `${colors.yellowBright(\"warlock.config.ts\")} has no recognisable defineConfig({...}) — ` +\r\n        \"add `connectors: [webConnector()]` yourself.\",\r\n    );\r\n\r\n    return;\r\n  }\r\n\r\n  await putFileAsync(configPath, next);\r\n  console.log(`${colors.green(\"✓\")} Registered webConnector in warlock.config.ts`);\r\n}\r\n\r\n/**\r\n * The app routes file the project template registers `GET /` in. Only this one\r\n * path is inspected: `warlock add web` is not a codebase-wide route auditor, and\r\n * a project that keeps its routes elsewhere lands on the `absent` outcome below,\r\n * which writes the page exactly as before.\r\n */\r\nconst APP_ROUTES_FILE = \"app/shared/routes.ts\";\r\n\r\n/**\r\n * A TOP-LEVEL `router.get(\"/\", ...)` — anchored at column 0 on purpose.\r\n *\r\n * Routes nested in a `router.group({ prefix: \"/x\" }, ...)` are indented by every\r\n * formatter this codebase runs, and their real path is `/x`, not `/`. Anchoring\r\n * is what keeps the notifications feature's own `router.get(\"/\", ...)` (inside\r\n * the `/notifications` group) from reading as a homepage collision.\r\n *\r\n * Only the path literal is captured. The handler — a bare identifier in the\r\n * template, but possibly an inline arrow spanning lines — is never matched, so\r\n * the rewrite below cannot damage it.\r\n */\r\nconst TOP_LEVEL_ROOT_GET = /^router\\s*\\.\\s*get\\(\\s*([\"'`])\\/\\1/gm;\r\n\r\n/**\r\n * Whether `/welcome` is already spoken for, so relocating onto it would trade\r\n * one duplicate-route 500 for another.\r\n */\r\nconst TOP_LEVEL_WELCOME_GET = /^router\\s*\\.\\s*get\\(\\s*([\"'`])\\/welcome\\1/m;\r\n\r\ntype HomeRouteCollision =\r\n  /** No app routes file, or nothing claims `/` — write the page as normal. */\r\n  | { outcome: \"absent\" }\r\n  /** The template's `GET /` was moved to `/welcome`; the page is safe to write. */\r\n  | { outcome: \"relocated\" }\r\n  /** Something claims `/` that we will not rewrite. The page is NOT written. */\r\n  | { outcome: \"conflict\"; reason: string }\r\n  /** We tried to relocate and could not. The page is NOT written. */\r\n  | { outcome: \"failed\"; reason: string };\r\n\r\n/**\r\n * Make room for a page that declares `route = \"/\"`.\r\n *\r\n * The project template registers `router.get(\"/\", homePageController)` and the\r\n * page stub declares `route = \"/\"`. Fastify rejects the second registration\r\n * (`Method 'GET' already declared for route '/'`) and the homepage 500s at\r\n * request time — so `warlock add web` cannot just write the page and hope.\r\n *\r\n * Of the three ways out, this RELOCATES the JSON route to `/welcome` rather than\r\n * deleting it or refusing to scaffold:\r\n *\r\n * - Deleting the controller is what the scaffolder's own `react` feature does,\r\n *   but it may do that: it owns the file it is deleting, seconds after writing\r\n *   it. `warlock add web` runs against a project a human has been living in, and\r\n *   silently unlinking their code is not a thing an `add` command gets to do.\r\n * - Writing the page anyway and printing a warning ships a project whose\r\n *   homepage 500s. A warning above a broken app is still a broken app.\r\n * - Relocating keeps BOTH surfaces working: the React homepage takes `/`, the\r\n *   JSON welcome answers at `/welcome`, and no line of user code disappears.\r\n *\r\n * Only the exact top-level shape is rewritten, and only the path literal inside\r\n * it. Anything else that claims `/` is reported and left completely alone — we\r\n * do not guess at code we cannot recognise.\r\n */\r\nasync function relocateConflictingHomeRoute(): Promise<HomeRouteCollision> {\r\n  const routesPath = srcPath(APP_ROUTES_FILE);\r\n\r\n  // Not every project comes from the template. No file is not a problem.\r\n  if (!(await fileExistsAsync(routesPath))) {\r\n    return { outcome: \"absent\" };\r\n  }\r\n\r\n  let current: string;\r\n\r\n  try {\r\n    current = await getFileAsync(routesPath);\r\n  } catch (error) {\r\n    return {\r\n      outcome: \"failed\",\r\n      reason: `could not be read (${(error as Error).message})`,\r\n    };\r\n  }\r\n\r\n  const matches = current.match(TOP_LEVEL_ROOT_GET) ?? [];\r\n\r\n  if (matches.length === 0) {\r\n    return { outcome: \"absent\" };\r\n  }\r\n\r\n  if (matches.length > 1) {\r\n    return {\r\n      outcome: \"conflict\",\r\n      reason: `declares ${matches.length} top-level GET \"/\" routes`,\r\n    };\r\n  }\r\n\r\n  if (TOP_LEVEL_WELCOME_GET.test(current)) {\r\n    return {\r\n      outcome: \"conflict\",\r\n      reason: 'already declares GET \"/welcome\", so the usual relocation target is taken',\r\n    };\r\n  }\r\n\r\n  const next = current.replace(TOP_LEVEL_ROOT_GET, (match, quote: string) =>\r\n    match.replace(`${quote}/${quote}`, `${quote}/welcome${quote}`),\r\n  );\r\n\r\n  if (next === current) {\r\n    return { outcome: \"conflict\", reason: 'its GET \"/\" route could not be rewritten' };\r\n  }\r\n\r\n  try {\r\n    await putFileAsync(routesPath, next);\r\n  } catch (error) {\r\n    return {\r\n      outcome: \"failed\",\r\n      reason: `could not be written (${(error as Error).message})`,\r\n    };\r\n  }\r\n\r\n  return { outcome: \"relocated\" };\r\n}\r\n\r\n/**\r\n * Scaffold the smallest page layer that renders, and register the connector.\r\n *\r\n * `src/web/root.tsx` is the sentinel for \"already scaffolded\" — the framework\r\n * ships a default root, so its presence means a human has been here.\r\n */\r\nasync function completeWebInstallation(_options: CommandActionData) {\r\n  const rootFile = srcPath(\"web/root.tsx\");\r\n\r\n  if (await fileExistsAsync(rootFile)) {\r\n    console.log(`${colors.yellowBright(\"src/web\")} already scaffolded, skipping...`);\r\n  } else {\r\n    await ensureDirectoryAsync(srcPath(\"web\"));\r\n    await putFileAsync(rootFile, webRootStub);\r\n    console.log(`${colors.green(\"✓\")} Created src/web/root.tsx`);\r\n\r\n    const collision = await relocateConflictingHomeRoute();\r\n\r\n    if (collision.outcome === \"relocated\") {\r\n      console.log(\r\n        `${colors.green(\"✓\")} Moved the existing ${colors.yellowBright('GET \"/\"')} route to ` +\r\n          `${colors.yellowBright('\"/welcome\"')} in ${colors.yellowBright(`src/${APP_ROUTES_FILE}`)} — ` +\r\n          \"the new page owns `/` now, and the JSON welcome route still answers at /welcome.\",\r\n      );\r\n    }\r\n\r\n    // The page is written ONLY when `/` is provably free. Writing it while\r\n    // another handler holds `/` produces a homepage that 500s on first request,\r\n    // which is precisely the outcome a scaffolder must never hand back.\r\n    if (collision.outcome === \"conflict\" || collision.outcome === \"failed\") {\r\n      const verb = collision.outcome === \"failed\" ? colors.redBright(\"✗\") : colors.yellowBright(\"!\");\r\n\r\n      console.log(\r\n        `${verb} Did not create src/web/home.page.tsx: ` +\r\n          `${colors.yellowBright(`src/${APP_ROUTES_FILE}`)} ${collision.reason}.\\n` +\r\n          `  The page stub declares ${colors.yellowBright('route = \"/\"')}, and two handlers on one ` +\r\n          \"path is a 500 at request time, not a startup error.\\n\" +\r\n          `  Free up ${colors.yellowBright('GET \"/\"')} in that file — move it to a path of its own, ` +\r\n          \"or remove it — then create src/web/home.page.tsx yourself. Giving the page a `route` other \" +\r\n          \"than `/` works too.\",\r\n      );\r\n\r\n      // Non-zero on BOTH branches. The page layer this command exists to\r\n      // scaffold was not scaffolded, and a 0 here is the exact \"looked like it\r\n      // worked\" signal that put `/` in this state to begin with — a conflict we\r\n      // declined to guess at is still an incomplete install, not a success.\r\n      //\r\n      // `exitCode` rather than `exit(1)`: the connector below still has to be\r\n      // registered, and any other feature in the same `warlock add` invocation\r\n      // still has to install, or the project is left half-wired on top of this.\r\n      process.exitCode = 1;\r\n    } else {\r\n      await putFileAsync(srcPath(\"web/home.page.tsx\"), webHomePageStub);\r\n      console.log(`${colors.green(\"✓\")} Created src/web/home.page.tsx`);\r\n    }\r\n  }\r\n\r\n  await registerWebConnector();\r\n}\r\n\r\nexport const webFeature: FeatureDefinition = {\r\n  description:\r\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.\",\r\n  dependencies: {\r\n    \"@warlock.js/web\": \"~4.0.0\",\r\n    react: \"^19.2.3\",\r\n    \"react-dom\": \"^19.2.3\",\r\n  },\r\n  devDependencies: {\r\n    \"@types/react\": \"^19.2.7\",\r\n    \"@types/react-dom\": \"^19.2.3\",\r\n    // Loaded through `await import()` by the dev server only, so both are\r\n    // optional peers of `web` rather than hard dependencies.\r\n    vite: \"^7.3.5\",\r\n    \"@vitejs/plugin-react\": \"^5.2.0\",\r\n  },\r\n  onExecuting: completeWebInstallation,\r\n};\r\n"],"mappings":"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"}
+{"version":3,"file":"web.feature.mjs","names":[],"sources":["../../../../../../../../core/src/generations/features/web.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\r\nimport {\r\n  ensureDirectoryAsync,\r\n  fileExistsAsync,\r\n  getFileAsync,\r\n  putFileAsync,\r\n} from \"@warlock.js/fs\";\r\nimport { CommandActionData } from \"../../commands/types\";\r\nimport { rootPath, srcPath } from \"../../utils\";\r\nimport {\n  webContactControllerStub,\n  webContactRoutesStub,\n  webHomePageStub,\n  webRootStub,\n} from \"../stubs\";\nimport { FeatureDefinition, INSTALLED_WARLOCK_VERSION } from \"./types\";\n\r\n/**\r\n * Register the WebConnector in `warlock.config.ts`, and ONLY there.\r\n *\r\n * It belongs to the config array or to app code, never both. Both halves are\r\n * registered before app code loads — the CLI preloader in dev, the generated\r\n * entry in production — so also calling `connectorsManager.register(...)` in\r\n * `src/app/main.ts` boots the connector twice and installs every page route\r\n * twice. That surfaces at PRODUCTION boot as `Route name \"...\" is already\r\n * taken`, because pages and API routes share one route-name namespace.\r\n *\r\n * The config array is the half to prefer: `warlock build` reads the same array\r\n * to drain each connector's build contribution, so \"built for\" and \"boots with\"\r\n * cannot drift.\r\n *\r\n * String surgery rather than a TypeScript parse: `warlock.config.ts` is an\r\n * app-owned file that may carry any formatting, and a parse-and-print would\r\n * reformat the parts we did not come to change.\r\n */\r\nasync function registerWebConnector(): Promise<void> {\r\n  const configPath = rootPath(\"warlock.config.ts\");\r\n\r\n  if (!(await fileExistsAsync(configPath))) {\r\n    console.log(\r\n      `${colors.yellowBright(\"warlock.config.ts\")} not found — add this yourself:\\n` +\r\n        `  import { webConnector } from \"@warlock.js/web/connector\";\\n` +\r\n        `  export default defineConfig({ connectors: [webConnector()] });`,\r\n    );\r\n\r\n    return;\r\n  }\r\n\r\n  const current = await getFileAsync(configPath);\r\n\r\n  if (current.includes(\"webConnector\")) {\r\n    console.log(`${colors.yellowBright(\"webConnector\")} already registered, skipping...`);\r\n\r\n    return;\r\n  }\r\n\r\n  const importLine = 'import { webConnector } from \"@warlock.js/web/connector\";';\r\n  let next = current.includes(importLine) ? current : `${importLine}\\n${current}`;\r\n\r\n  // An existing `connectors: [` gains one entry; otherwise the key is added to\r\n  // the object `defineConfig` receives.\r\n  if (/connectors:\\s*\\[/.test(next)) {\r\n    next = next.replace(/connectors:\\s*\\[/, \"connectors: [webConnector(),\");\r\n  } else if (next.includes(\"defineConfig({\")) {\r\n    next = next.replace(\"defineConfig({\", \"defineConfig({\\n  connectors: [webConnector()],\");\r\n  } else {\r\n    console.log(\r\n      `${colors.yellowBright(\"warlock.config.ts\")} has no recognisable defineConfig({...}) — ` +\r\n        \"add `connectors: [webConnector()]` yourself.\",\r\n    );\r\n\r\n    return;\r\n  }\r\n\r\n  await putFileAsync(configPath, next);\r\n  console.log(`${colors.green(\"✓\")} Registered webConnector in warlock.config.ts`);\r\n}\r\n\r\n/**\r\n * The app routes file the project template registers `GET /` in. Only this one\r\n * path is inspected: `warlock add web` is not a codebase-wide route auditor, and\r\n * a project that keeps its routes elsewhere lands on the `absent` outcome below,\r\n * which writes the page exactly as before.\r\n */\r\nconst APP_ROUTES_FILE = \"app/shared/routes.ts\";\r\n\r\n/**\r\n * A TOP-LEVEL `router.get(\"/\", ...)` — anchored at column 0 on purpose.\r\n *\r\n * Routes nested in a `router.group({ prefix: \"/x\" }, ...)` are indented by every\r\n * formatter this codebase runs, and their real path is `/x`, not `/`. Anchoring\r\n * is what keeps the notifications feature's own `router.get(\"/\", ...)` (inside\r\n * the `/notifications` group) from reading as a homepage collision.\r\n *\r\n * Only the path literal is captured. The handler — a bare identifier in the\r\n * template, but possibly an inline arrow spanning lines — is never matched, so\r\n * the rewrite below cannot damage it.\r\n */\r\nconst TOP_LEVEL_ROOT_GET = /^router\\s*\\.\\s*get\\(\\s*([\"'`])\\/\\1/gm;\r\n\r\n/**\r\n * Whether `/welcome` is already spoken for, so relocating onto it would trade\r\n * one duplicate-route 500 for another.\r\n */\r\nconst TOP_LEVEL_WELCOME_GET = /^router\\s*\\.\\s*get\\(\\s*([\"'`])\\/welcome\\1/m;\r\n\r\ntype HomeRouteCollision =\r\n  /** No app routes file, or nothing claims `/` — write the page as normal. */\r\n  | { outcome: \"absent\" }\r\n  /** The template's `GET /` was moved to `/welcome`; the page is safe to write. */\r\n  | { outcome: \"relocated\" }\r\n  /** Something claims `/` that we will not rewrite. The page is NOT written. */\r\n  | { outcome: \"conflict\"; reason: string }\r\n  /** We tried to relocate and could not. The page is NOT written. */\r\n  | { outcome: \"failed\"; reason: string };\r\n\r\n/**\r\n * Make room for a page that declares `route = \"/\"`.\r\n *\r\n * The project template registers `router.get(\"/\", homePageController)` and the\r\n * page stub declares `route = \"/\"`. Fastify rejects the second registration\r\n * (`Method 'GET' already declared for route '/'`) and the homepage 500s at\r\n * request time — so `warlock add web` cannot just write the page and hope.\r\n *\r\n * Of the three ways out, this RELOCATES the JSON route to `/welcome` rather than\r\n * deleting it or refusing to scaffold:\r\n *\r\n * - Deleting the controller is what the scaffolder's own `react` feature does,\r\n *   but it may do that: it owns the file it is deleting, seconds after writing\r\n *   it. `warlock add web` runs against a project a human has been living in, and\r\n *   silently unlinking their code is not a thing an `add` command gets to do.\r\n * - Writing the page anyway and printing a warning ships a project whose\r\n *   homepage 500s. A warning above a broken app is still a broken app.\r\n * - Relocating keeps BOTH surfaces working: the React homepage takes `/`, the\r\n *   JSON welcome answers at `/welcome`, and no line of user code disappears.\r\n *\r\n * Only the exact top-level shape is rewritten, and only the path literal inside\r\n * it. Anything else that claims `/` is reported and left completely alone — we\r\n * do not guess at code we cannot recognise.\r\n */\r\nasync function relocateConflictingHomeRoute(): Promise<HomeRouteCollision> {\r\n  const routesPath = srcPath(APP_ROUTES_FILE);\r\n\r\n  // Not every project comes from the template. No file is not a problem.\r\n  if (!(await fileExistsAsync(routesPath))) {\r\n    return { outcome: \"absent\" };\r\n  }\r\n\r\n  let current: string;\r\n\r\n  try {\r\n    current = await getFileAsync(routesPath);\r\n  } catch (error) {\r\n    return {\r\n      outcome: \"failed\",\r\n      reason: `could not be read (${(error as Error).message})`,\r\n    };\r\n  }\r\n\r\n  const matches = current.match(TOP_LEVEL_ROOT_GET) ?? [];\r\n\r\n  if (matches.length === 0) {\r\n    return { outcome: \"absent\" };\r\n  }\r\n\r\n  if (matches.length > 1) {\r\n    return {\r\n      outcome: \"conflict\",\r\n      reason: `declares ${matches.length} top-level GET \"/\" routes`,\r\n    };\r\n  }\r\n\r\n  if (TOP_LEVEL_WELCOME_GET.test(current)) {\r\n    return {\r\n      outcome: \"conflict\",\r\n      reason: 'already declares GET \"/welcome\", so the usual relocation target is taken',\r\n    };\r\n  }\r\n\r\n  const next = current.replace(TOP_LEVEL_ROOT_GET, (match, quote: string) =>\r\n    match.replace(`${quote}/${quote}`, `${quote}/welcome${quote}`),\r\n  );\r\n\r\n  if (next === current) {\r\n    return { outcome: \"conflict\", reason: 'its GET \"/\" route could not be rewritten' };\r\n  }\r\n\r\n  try {\r\n    await putFileAsync(routesPath, next);\r\n  } catch (error) {\r\n    return {\r\n      outcome: \"failed\",\r\n      reason: `could not be written (${(error as Error).message})`,\r\n    };\r\n  }\r\n\r\n  return { outcome: \"relocated\" };\r\n}\r\n\r\n/**\r\n * Scaffold the smallest page layer that renders, and register the connector.\r\n *\r\n * `src/web/root.tsx` is the sentinel for \"already scaffolded\" — the framework\r\n * ships a default root, so its presence means a human has been here.\r\n */\r\nasync function completeWebInstallation(_options: CommandActionData) {\r\n  const rootFile = srcPath(\"web/root.tsx\");\r\n\r\n  if (await fileExistsAsync(rootFile)) {\r\n    console.log(`${colors.yellowBright(\"src/web\")} already scaffolded, skipping...`);\r\n  } else {\r\n    await ensureDirectoryAsync(srcPath(\"web\"));\r\n    await putFileAsync(rootFile, webRootStub);\r\n    console.log(`${colors.green(\"✓\")} Created src/web/root.tsx`);\r\n\r\n    const collision = await relocateConflictingHomeRoute();\r\n\r\n    if (collision.outcome === \"relocated\") {\r\n      console.log(\r\n        `${colors.green(\"✓\")} Moved the existing ${colors.yellowBright('GET \"/\"')} route to ` +\r\n          `${colors.yellowBright('\"/welcome\"')} in ${colors.yellowBright(`src/${APP_ROUTES_FILE}`)} — ` +\r\n          \"the new page owns `/` now, and the JSON welcome route still answers at /welcome.\",\r\n      );\r\n    }\r\n\r\n    // The page is written ONLY when `/` is provably free. Writing it while\r\n    // another handler holds `/` produces a homepage that 500s on first request,\r\n    // which is precisely the outcome a scaffolder must never hand back.\r\n    if (collision.outcome === \"conflict\" || collision.outcome === \"failed\") {\r\n      const verb = collision.outcome === \"failed\" ? colors.redBright(\"✗\") : colors.yellowBright(\"!\");\r\n\r\n      console.log(\r\n        `${verb} Did not create src/web/home.page.tsx: ` +\r\n          `${colors.yellowBright(`src/${APP_ROUTES_FILE}`)} ${collision.reason}.\\n` +\r\n          `  The page stub declares ${colors.yellowBright('route = \"/\"')}, and two handlers on one ` +\r\n          \"path is a 500 at request time, not a startup error.\\n\" +\r\n          `  Free up ${colors.yellowBright('GET \"/\"')} in that file — move it to a path of its own, ` +\r\n          \"or remove it — then create src/web/home.page.tsx yourself. Giving the page a `route` other \" +\r\n          \"than `/` works too.\",\r\n      );\r\n\r\n      // Non-zero on BOTH branches. The page layer this command exists to\r\n      // scaffold was not scaffolded, and a 0 here is the exact \"looked like it\r\n      // worked\" signal that put `/` in this state to begin with — a conflict we\r\n      // declined to guess at is still an incomplete install, not a success.\r\n      //\r\n      // `exitCode` rather than `exit(1)`: the connector below still has to be\r\n      // registered, and any other feature in the same `warlock add` invocation\r\n      // still has to install, or the project is left half-wired on top of this.\r\n      process.exitCode = 1;\r\n    } else {\n      await putFileAsync(srcPath(\"web/home.page.tsx\"), webHomePageStub);\n      await ensureDirectoryAsync(srcPath(\"app/contact/controllers\"));\n      await putFileAsync(\n        srcPath(\"app/contact/controllers/contact.controller.ts\"),\n        webContactControllerStub,\n      );\n      await putFileAsync(srcPath(\"app/contact/routes.ts\"), webContactRoutesStub);\n      console.log(`${colors.green(\"✓\")} Created src/web/home.page.tsx`);\n      console.log(`${colors.green(\"✓\")} Created POST /api/contact starter route`);\n    }\r\n  }\r\n\r\n  await registerWebConnector();\r\n}\r\n\r\nexport const webFeature: FeatureDefinition = {\r\n  description:\r\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.\",\r\n  dependencies: {\r\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\",\r\n    \"react-dom\": \"^19.2.3\",\r\n  },\r\n  devDependencies: {\r\n    \"@types/react\": \"^19.2.7\",\r\n    \"@types/react-dom\": \"^19.2.3\",\r\n    // Loaded through `await import()` by the dev server only, so both are\r\n    // optional peers of `web` rather than hard dependencies.\r\n    vite: \"^7.3.5\",\r\n    \"@vitejs/plugin-react\": \"^5.2.0\",\r\n  },\r\n  onExecuting: completeWebInstallation,\r\n};\r\n"],"mappings":"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"}

package/esm/generations/stubs.mjs

@@ -631,11 +631,51 @@ export default function App({ children }: AppProps) {
 }
 `;
 /**
+* `src/app/contact/controllers/contact.controller.ts` — a real API endpoint
+* for the Web starter's contact form. It intentionally has no persistence
+* dependency: replace the acknowledgement with a mail/job/database action.
+*/
+const webContactControllerStub = `import { type Request, type RequestHandler } from "@warlock.js/core";
+import { type Infer, v } from "@warlock.js/seal";
+
+export const contactSchema = v.object({
+  name: v.string().min(2).required(),
+  email: v.email().required(),
+  message: v.string().min(10).required(),
+});
+
+export type ContactSchema = Infer.Output<typeof contactSchema>;
+
+/** POST /api/contact — validates the starter contact form. */
+export const contactController: RequestHandler<Request<ContactSchema>> = async ({ request, response }) => {
+  const contact = request.validated();
+
+  // Replace this with delivery/persistence for your app. Keeping the accepted
+  // payload visible makes the endpoint useful while remaining side-effect free.
+  return response.success({
+    message: "Thanks, " + contact.name + ". Your message has been received.",
+  });
+};
+
+contactController.validation = { schema: contactSchema };
+`;
+/** `src/app/contact/routes.ts` — discovered by the standard app route loader. */
+const webContactRoutesStub = `import { router } from "@warlock.js/core";
+import { contactController } from "./controllers/contact.controller";
+
+router.post("/api/contact", contactController);
+`;
+/**
 * `src/web/home.page.tsx` — one page, so \`warlock dev\` has something to serve
 * the moment this finishes.
 */
-const webHomePageStub = `import { useState } from "react";
-import type { PageProps } from "@warlock.js/web";
+const webHomePageStub = `import { http } from "@mongez/http";
+import { Form, useFormControl, type FormControlProps } from "@mongez/react-form";
+import { extend, setCurrentLocaleCode } from "@mongez/localization";
+import { transX } from "@mongez/react-localization";
+import { v } from "@warlock.js/seal";
+import { useState } from "react";
+import { Link, type PageProps } from "@warlock.js/web";
 
 /**
  * A page route is an ordinary Warlock route whose handler renders React
@@ -649,6 +689,51 @@ export const route = "/";
 
 export const metadata = { title: "Home" };
 
+const contactSchema = v.object({
+  name: v.string().min(2).required(),
+  email: v.email().required(),
+  message: v.string().min(10).required(),
+});
+
+extend("en", {
+  starter: {
+    title: "Your Warlock app is running.",
+    introduction: "This page is rendered on the server and hydrated in the browser.",
+    language: "العربية",
+    contact: "Send a message",
+    name: "Name",
+    email: "Email",
+    message: "Message",
+    submit: "Send message",
+    sent: "Thanks — your message has been received.",
+  },
+});
+extend("ar", {
+  starter: {
+    title: "تطبيق Warlock يعمل الآن.",
+    introduction: "تُعرض هذه الصفحة على الخادم ثم تُفعَّل في المتصفح.",
+    language: "English",
+    contact: "أرسل رسالة",
+    name: "الاسم",
+    email: "البريد الإلكتروني",
+    message: "الرسالة",
+    submit: "إرسال الرسالة",
+    sent: "شكرًا — تم استلام رسالتك.",
+  },
+});
+
+function TextInput({ label, ...controlProps }: FormControlProps & { label: string }) {
+  const { error, getErrorProps, getInputProps } = useFormControl(controlProps);
+
+  return (
+    <div className="wk-field">
+      <label htmlFor={controlProps.name}>{label}</label>
+      <input {...getInputProps()} />
+      {error && <p {...getErrorProps()}>{error}</p>}
+    </div>
+  );
+}
+
 /**
  * Add a \`loader\` export to fetch data on the server, and it arrives here as
  * \`data\`, typed:
@@ -661,6 +746,15 @@ export default function HomePage(_props: PageProps) {
   // server but never hydrated — the runtime never mounted at \`#root\`. This is
   // deliberately here so that failure is impossible to miss.
   const [count, setCount] = useState(0);
+  const [locale, setLocale] = useState<"en" | "ar">("en");
+  const [submitted, setSubmitted] = useState(false);
+  const [submitError, setSubmitError] = useState<string | null>(null);
+
+  const toggleLocale = () => {
+    const nextLocale = locale === "en" ? "ar" : "en";
+    setCurrentLocaleCode(nextLocale);
+    setLocale(nextLocale);
+  };
 
   return (
     <>
@@ -711,15 +805,30 @@ export default function HomePage(_props: PageProps) {
         .wk-links { display: flex; gap: 1.25rem; font-size: 0.95rem; }
         .wk-links a { color: var(--wk-accent); text-decoration: none; }
         .wk-links a:hover { text-decoration: underline; }
+        .wk-language { margin-left: auto; }
+        .wk-contact { margin-top: 2rem; }
+        .wk-field { display: grid; gap: 0.35rem; margin: 0.8rem 0; }
+        .wk-field input, .wk-field textarea { font: inherit; padding: 0.55rem; }
+        .wk-field p, .wk-submit-error { color: #b91c1c; margin: 0; }
+        .wk-success { color: #047857; }
       \`}</style>
 
-      <main className="wk-home">
-        <h1>Your Warlock app is running.</h1>
-        <p>
-          This is <code>src/web/home.page.tsx</code>, an SSR React page served by
-          the Warlock HTTP server. Edit it and the browser updates without
-          losing state.
-        </p>
+      <main className="wk-home" dir={locale === "ar" ? "rtl" : "ltr"}>
+        <nav className="wk-links" aria-label="Starter links">
+          <a href="https://warlock.js.org" target="_blank" rel="noreferrer">Docs</a>
+          <Link href="/" aria-current="page">Home</Link>
+          <button
+            className="wk-language"
+            type="button"
+            aria-pressed={locale === "ar"}
+            onClick={toggleLocale}
+          >
+            {transX("starter.language")}
+          </button>
+        </nav>
+
+        <h1>{transX("starter.title")}</h1>
+        <p>{transX("starter.introduction")}</p>
 
         <section className="wk-check">
           <label>If this number goes up when you click, React is hydrated:</label>
@@ -729,31 +838,63 @@ export default function HomePage(_props: PageProps) {
           </button>
         </section>
 
-        <nav className="wk-links">
-          <a href="https://warlock.js.org" target="_blank" rel="noreferrer">
-            Docs
-          </a>
-          <a
-            href="https://warlock.js.org/web"
-            target="_blank"
-            rel="noreferrer"
-          >
-            Web / SSR pages
-          </a>
-          <a
-            href="https://github.com/hassanzohdy/warlock"
-            target="_blank"
-            rel="noreferrer"
+        <section className="wk-contact" aria-labelledby="contact-heading">
+          <h2 id="contact-heading">{transX("starter.contact")}</h2>
+          <Form<typeof contactSchema>
+            schema={contactSchema}
+            onSubmit={async ({ form, values }) => {
+              setSubmitted(false);
+              setSubmitError(null);
+              const result = await http.post<{ message: string }>("/api/contact", values);
+
+              if (result.error) {
+                if (result.error.isValidationError) {
+                  const body = result.error.body as {
+                    errors?: Array<{ input: string; error: string }>;
+                    message?: string;
+                  };
+                  form.setErrors(
+                    Object.fromEntries(
+                      (body.errors ?? []).map(({ input, error }) => [input, error]),
+                    ),
+                  );
+                  setSubmitError(body.message ?? "Please correct the highlighted fields.");
+                } else {
+                  setSubmitError("Your message could not be sent. Please try again.");
+                }
+                return;
+              }
+
+              setSubmitted(true);
+              form.reset();
+            }}
           >
-            GitHub
-          </a>
-        </nav>
+            <TextInput name="name" label={transX("starter.name")} autoComplete="name" />
+            <TextInput name="email" label={transX("starter.email")} type="email" autoComplete="email" />
+            <ContactMessage />
+            <button type="submit">{transX("starter.submit")}</button>
+            {submitError && <p className="wk-submit-error" role="alert">{submitError}</p>}
+            {submitted && <p className="wk-success" role="status">{transX("starter.sent")}</p>}
+          </Form>
+        </section>
       </main>
     </>
   );
 }
+
+function ContactMessage() {
+  const { error, getErrorProps, getInputProps } = useFormControl({ name: "message" });
+
+  return (
+    <div className="wk-field">
+      <label htmlFor="message">{transX("starter.message")}</label>
+      <textarea {...getInputProps()} rows={5} />
+      {error && <p {...getErrorProps()}>{error}</p>}
+    </div>
+  );
+}
 `;
 
 //#endregion
-export { accessConfigStub, accessResolverStub, accessRoleMigrationStub, accessRoleModelIndexStub, accessRoleModelStub, accessUserRoleMigrationStub, accessUserRoleModelIndexStub, accessUserRoleModelStub, aiConfigStub, communicatorsConfigStub, notificationControllersStub, notificationMigrationStub, notificationModelStub, notificationRoutesStub, notificationsConfigStub, socketConfigStub, webHomePageStub, webRootStub };
+export { accessConfigStub, accessResolverStub, accessRoleMigrationStub, accessRoleModelIndexStub, accessRoleModelStub, accessUserRoleMigrationStub, accessUserRoleModelIndexStub, accessUserRoleModelStub, aiConfigStub, communicatorsConfigStub, notificationControllersStub, notificationMigrationStub, notificationModelStub, notificationRoutesStub, notificationsConfigStub, socketConfigStub, webContactControllerStub, webContactRoutesStub, webHomePageStub, webRootStub };
 //# sourceMappingURL=stubs.mjs.map