@warlock.js/core 5.0.1 → 5.1.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"shadcn.feature.mjs","names":[],"sources":["../../../../../../../../core/src/generations/features/shadcn.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from \"@warlock.js/fs\";\nimport { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport { FeatureDefinition } from \"./types\";\n\n/**\n * `warlock add shadcn` installs the PREREQUISITES for shadcn/ui. It does not\n * wrap `shadcn add`, and it never will.\n *\n * shadcn/ui is a copy-in generator with its own CLI and its own registry, not a\n * dependency: components are written into your source tree and become yours the\n * moment they land. Wrapping their CLI would make their moving target our bug\n * reports, for a command that adds nothing but a rename.\n *\n * What is worth owning is the part their CLI gets wrong here. Measured against\n * this framework's layout on 2026-08-25, `shadcn add button card` exited 0 and\n * produced components that rendered COMPLETELY UNSTYLED. It writes components\n * that import `cn` and reference `bg-primary` / `ring-ring`, but only\n * `shadcn init` creates `lib/utils` and the theme tokens those names resolve\n * against. The class was in the generated CSS and the element carried it, and\n * the rule still evaluated to an empty `var()` — a silent failure with a zero\n * exit code, which is the worst kind to hand a user.\n *\n * So this feature ships the five things that make `npx shadcn add <component>`\n * work the first time:\n *\n *   1. `components.json` written for OUR layout (their defaults assume `src/app`\n *      or a bare `components/`, neither of which is where pages live here).\n *   2. `src/web/lib/utils.ts` exporting `cn`.\n *   3. The design tokens appended to `src/web/app.css`.\n *   4. A `web/*` entry in tsconfig `paths`, so the generated imports typecheck.\n *   5. The packages `init` would have installed — see `printNextStep` below.\n *      Skipping `init` is correct; skipping its dependency list was a bug, and\n *      it cost a generated button that imports `cva` and cannot compile.\n *\n * After that, the user talks to shadcn directly, and their docs are true.\n */\n\n/**\n * The aliases shadcn's CLI rewrites every generated import against.\n *\n * These are the whole reason this feature exists. shadcn's defaults do not fit\n * `src/web`, and no user would guess this mapping: the alias keys are shadcn's\n * vocabulary, the values are tsconfig `paths` prefixes (hence `web/...`, not\n * `src/web/...`), and `tailwind.css` is a real path from the project root\n * (hence `src/web/app.css`, WITH the `src`). Getting one of them wrong produces\n * components in the wrong folder importing `cn` from somewhere that does not\n * exist.\n *\n * `tailwind.config` is deliberately empty: v4 is CSS-first and there is no\n * config file for it to point at. `rsc: false` because these are SSR React\n * pages rendered by the Warlock HTTP server, not React Server Components.\n */\nconst componentsJsonStub = `{\n  \"$schema\": \"https://ui.shadcn.com/schema.json\",\n  \"style\": \"new-york\",\n  \"rsc\": false,\n  \"tsx\": true,\n  \"tailwind\": {\n    \"config\": \"\",\n    \"css\": \"src/web/app.css\",\n    \"baseColor\": \"neutral\",\n    \"cssVariables\": true,\n    \"prefix\": \"\"\n  },\n  \"aliases\": {\n    \"components\": \"web/components\",\n    \"utils\": \"web/lib/utils\",\n    \"ui\": \"web/components/ui\",\n    \"lib\": \"web/lib\",\n    \"hooks\": \"web/hooks\"\n  },\n  \"iconLibrary\": \"lucide\"\n}\n`;\n\n/**\n * `cn` — the one import every single shadcn component makes.\n *\n * `clsx` resolves the conditional/array/object class syntax, and `tailwind-merge`\n * then de-duplicates conflicting Tailwind utilities so a caller's `className`\n * actually beats the component's own default rather than depending on which one\n * happens to come later in the generated stylesheet. Both halves are required:\n * clsx alone leaves `px-2 px-4` in the attribute and the loser wins at random.\n */\nconst cnUtilStub = `import { clsx, type ClassValue } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * Merge class names, with later Tailwind utilities winning over earlier ones.\n *\n * Every shadcn/ui component imports this. Keep the export name and signature.\n */\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n`;\n\n/**\n * Marker for \"the tokens are already in this stylesheet\".\n *\n * A comment rather than a token name, because a user is free to retune every\n * value below and we must still recognise our own block on a re-run.\n */\nconst SHADCN_TOKENS_MARKER = \"shadcn/ui design tokens\";\n\n/**\n * The shadcn token set, as a plain `@theme` block with LITERAL values.\n *\n * Not `@theme inline` over `:root` custom properties, which is what shadcn's own\n * `init` writes. That form was verified against this stylesheet pipeline on\n * 2026-08-25 and it produces utilities that resolve to nothing: the class is in\n * the generated CSS, the class is on the element, and the rule still evaluates\n * to an empty `var()`. Literal values in `@theme` are what make `bg-primary`\n * emit a colour instead of a dangling reference.\n *\n * Dark mode still works, and works the way shadcn expects: `@theme` emits these\n * as real custom properties, so the `.dark` block re-declares the same\n * `--color-*` names and the cascade does the rest. `@custom-variant dark` is\n * what points Tailwind's `dark:` prefix at that class instead of the OS setting.\n *\n * Values are shadcn's `neutral` base. They are the starting point, not the\n * answer — this is the block to edit when the project gets a real palette.\n */\nconst shadcnTokensStub = `\n/* ${SHADCN_TOKENS_MARKER} — edit freely, this is your palette now.\n\n   These are LITERAL values in a plain @theme block, on purpose. shadcn's own\n   \\`init\\` writes \\`@theme inline\\` over :root custom properties; that form emits\n   utilities which resolve to an empty var() here, so every component renders\n   unstyled while the class sits right there on the element. Do not convert it.\n*/\n@custom-variant dark (&:is(.dark *));\n\n@theme {\n  --color-background: oklch(1 0 0);\n  --color-foreground: oklch(0.145 0 0);\n  --color-card: oklch(1 0 0);\n  --color-card-foreground: oklch(0.145 0 0);\n  --color-popover: oklch(1 0 0);\n  --color-popover-foreground: oklch(0.145 0 0);\n  --color-primary: oklch(0.205 0 0);\n  --color-primary-foreground: oklch(0.985 0 0);\n  --color-secondary: oklch(0.97 0 0);\n  --color-secondary-foreground: oklch(0.205 0 0);\n  --color-muted: oklch(0.97 0 0);\n  --color-muted-foreground: oklch(0.556 0 0);\n  --color-accent: oklch(0.97 0 0);\n  --color-accent-foreground: oklch(0.205 0 0);\n  --color-destructive: oklch(0.577 0.245 27.325);\n  --color-destructive-foreground: oklch(0.985 0 0);\n  --color-border: oklch(0.922 0 0);\n  --color-input: oklch(0.922 0 0);\n  --color-ring: oklch(0.708 0 0);\n\n  --color-chart-1: oklch(0.646 0.222 41.116);\n  --color-chart-2: oklch(0.6 0.118 184.704);\n  --color-chart-3: oklch(0.398 0.07 227.392);\n  --color-chart-4: oklch(0.828 0.189 84.429);\n  --color-chart-5: oklch(0.769 0.188 70.08);\n\n  --color-sidebar: oklch(0.985 0 0);\n  --color-sidebar-foreground: oklch(0.145 0 0);\n  --color-sidebar-primary: oklch(0.205 0 0);\n  --color-sidebar-primary-foreground: oklch(0.985 0 0);\n  --color-sidebar-accent: oklch(0.97 0 0);\n  --color-sidebar-accent-foreground: oklch(0.205 0 0);\n  --color-sidebar-border: oklch(0.922 0 0);\n  --color-sidebar-ring: oklch(0.708 0 0);\n\n  /* shadcn components reach for rounded-lg/md/sm and expect them to track one\n     radius. Changing --radius-lg here also retunes Tailwind's own rounded-lg,\n     which is the intended trade: one radius scale per project, not two. */\n  --radius-sm: 0.375rem;\n  --radius-md: 0.5rem;\n  --radius-lg: 0.625rem;\n  --radius-xl: 1rem;\n}\n\n.dark {\n  --color-background: oklch(0.145 0 0);\n  --color-foreground: oklch(0.985 0 0);\n  --color-card: oklch(0.205 0 0);\n  --color-card-foreground: oklch(0.985 0 0);\n  --color-popover: oklch(0.205 0 0);\n  --color-popover-foreground: oklch(0.985 0 0);\n  --color-primary: oklch(0.922 0 0);\n  --color-primary-foreground: oklch(0.205 0 0);\n  --color-secondary: oklch(0.269 0 0);\n  --color-secondary-foreground: oklch(0.985 0 0);\n  --color-muted: oklch(0.269 0 0);\n  --color-muted-foreground: oklch(0.708 0 0);\n  --color-accent: oklch(0.269 0 0);\n  --color-accent-foreground: oklch(0.985 0 0);\n  --color-destructive: oklch(0.704 0.191 22.216);\n  --color-destructive-foreground: oklch(0.985 0 0);\n  --color-border: oklch(1 0 0 / 10%);\n  --color-input: oklch(1 0 0 / 15%);\n  --color-ring: oklch(0.556 0 0);\n\n  --color-chart-1: oklch(0.488 0.243 264.376);\n  --color-chart-2: oklch(0.696 0.17 162.48);\n  --color-chart-3: oklch(0.769 0.188 70.08);\n  --color-chart-4: oklch(0.627 0.265 303.9);\n  --color-chart-5: oklch(0.645 0.246 16.439);\n\n  --color-sidebar: oklch(0.205 0 0);\n  --color-sidebar-foreground: oklch(0.985 0 0);\n  --color-sidebar-primary: oklch(0.488 0.243 264.376);\n  --color-sidebar-primary-foreground: oklch(0.985 0 0);\n  --color-sidebar-accent: oklch(0.269 0 0);\n  --color-sidebar-accent-foreground: oklch(0.985 0 0);\n  --color-sidebar-border: oklch(1 0 0 / 10%);\n  --color-sidebar-ring: oklch(0.556 0 0);\n}\n`;\n\n/**\n * Write `components.json` — the sentinel for \"this feature already ran\".\n *\n * Nothing in the project template creates this file, so its presence means\n * `add shadcn` has been here and a human may since have retuned the aliases,\n * the style, or the base colour. It is never rewritten: shadcn's CLI reads this\n * file on every `add`, so overwriting it would silently relocate a project's\n * component folder out from under the components already in it.\n */\nasync function writeComponentsJson(): Promise<void> {\n  const componentsJsonPath = rootPath(\"components.json\");\n\n  if (await fileExistsAsync(componentsJsonPath)) {\n    console.log(`${colors.yellowBright(\"components.json\")} already exists, skipping...`);\n\n    return;\n  }\n\n  await putFileAsync(componentsJsonPath, componentsJsonStub);\n  console.log(`${colors.green(\"✓\")} Created components.json`);\n}\n\n/**\n * Write `src/web/lib/utils.ts`.\n *\n * Guarded on its own rather than on the sentinel above, because `lib/utils` is\n * a name a project may well already own — and if it does, whatever is in there\n * is user code with other callers. We print instead of merging.\n */\nasync function writeCnUtil(): Promise<void> {\n  const utilsFile = srcPath(\"web/lib/utils.ts\");\n\n  if (await fileExistsAsync(utilsFile)) {\n    const current = await getFileAsync(utilsFile).catch(() => \"\");\n\n    if (/export\\s+(function|const)\\s+cn\\b/.test(current)) {\n      console.log(`${colors.yellowBright(\"src/web/lib/utils.ts\")} already exports cn, skipping...`);\n    } else {\n      console.log(\n        `${colors.yellowBright(\"!\")} ${colors.yellowBright(\"src/web/lib/utils.ts\")} exists but does not export ` +\n          `${colors.yellowBright(\"cn\")} — add it yourself:\\n` +\n          \"  export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }\\n\" +\n          \"  Every shadcn component imports it, and none of them will compile until it is there.\",\n      );\n    }\n\n    return;\n  }\n\n  await ensureDirectoryAsync(srcPath(\"web/lib\"));\n  await putFileAsync(utilsFile, cnUtilStub);\n  console.log(`${colors.green(\"✓\")} Created src/web/lib/utils.ts`);\n}\n\n/**\n * Append the token block to `src/web/app.css`.\n *\n * The stylesheet is guaranteed to exist by the time this runs: `requires:\n * [\"tailwind\"]` makes the add command resolve `tailwind` first and run its\n * `onExecuting` ahead of this one, and that is what creates the file. The check\n * below is for a stylesheet a human has since moved or deleted — worth a\n * printed instruction, not a failure.\n *\n * Appended, never rewritten. Everything already in that file is either\n * Tailwind's own `@import` or the project's design system.\n */\nasync function appendThemeTokens(): Promise<void> {\n  const cssFile = srcPath(\"web/app.css\");\n\n  if (!(await fileExistsAsync(cssFile))) {\n    console.log(\n      `${colors.yellowBright(\"!\")} ${colors.yellowBright(\"src/web/app.css\")} not found — ` +\n        \"append the shadcn token block to your Tailwind stylesheet yourself.\\n\" +\n        \"  Without the tokens, shadcn components render unstyled: the classes are emitted and applied, \" +\n        \"but `bg-primary` and friends resolve to an empty var().\",\n    );\n\n    return;\n  }\n\n  const current = await getFileAsync(cssFile);\n\n  if (current.includes(SHADCN_TOKENS_MARKER) || current.includes(\"--color-primary-foreground\")) {\n    console.log(`${colors.yellowBright(\"src/web/app.css\")} already has the tokens, skipping...`);\n\n    return;\n  }\n\n  await putFileAsync(cssFile, `${current.trimEnd()}\\n${shadcnTokensStub}`);\n  console.log(`${colors.green(\"✓\")} Appended the shadcn tokens to src/web/app.css`);\n}\n\n/** The tsconfig `paths` entry the generated imports resolve through. */\nconst WEB_PATH_ALIAS = '\"web/*\": [\"./src/web/*\"]';\n\n/**\n * Add `web/*` to tsconfig `compilerOptions.paths`.\n *\n * The template declares only `app/*`, so every import shadcn generates against\n * the aliases above (`web/lib/utils`, `web/components/ui/button`) would fail to\n * typecheck the moment it lands. This is the first `add` feature to patch\n * `paths` rather than `include`.\n *\n * String surgery, and NOT the parse-and-write that the `include` patches use.\n * The project template's `tsconfig.json` carries `//` comments — it is JSONC,\n * and `JSON.parse` throws on it — so a parse-first patch would fail on exactly\n * the projects this feature is for. Editing the text also preserves those\n * comments, which are load-bearing documentation in that file.\n */\nasync function addWebPathAlias(): Promise<void> {\n  const tsconfigPath = rootPath(\"tsconfig.json\");\n\n  const printManualInstruction = (reason: string) => {\n    console.log(\n      `${colors.yellowBright(\"!\")} ${colors.yellowBright(\"tsconfig.json\")} ${reason} — ` +\n        \"add this to `compilerOptions.paths` yourself:\\n\" +\n        `  ${WEB_PATH_ALIAS}\\n` +\n        \"  Without it, every import shadcn generates against the `web/*` aliases fails to typecheck.\",\n    );\n  };\n\n  if (!(await fileExistsAsync(tsconfigPath))) {\n    printManualInstruction(\"not found\");\n\n    return;\n  }\n\n  const current = await getFileAsync(tsconfigPath);\n\n  // Matches the alias whichever quote style and spacing the file uses, so a\n  // re-run against a hand-edited tsconfig does not stack a second entry.\n  if (/[\"']web\\/\\*[\"']\\s*:/.test(current)) {\n    console.log(`${colors.yellowBright(\"tsconfig.json\")} already maps web/*, skipping...`);\n\n    return;\n  }\n\n  let next: string;\n\n  if (/\"paths\"\\s*:\\s*\\{/.test(current)) {\n    next = current.replace(/\"paths\"\\s*:\\s*\\{/, `$&\\n      ${WEB_PATH_ALIAS},`);\n  } else if (/\"compilerOptions\"\\s*:\\s*\\{/.test(current)) {\n    next = current.replace(\n      /\"compilerOptions\"\\s*:\\s*\\{/,\n      `$&\\n    \"paths\": {\\n      ${WEB_PATH_ALIAS}\\n    },`,\n    );\n  } else {\n    printManualInstruction(\"has no recognisable compilerOptions block\");\n\n    return;\n  }\n\n  await putFileAsync(tsconfigPath, next);\n  console.log(`${colors.green(\"✓\")} Added ${WEB_PATH_ALIAS} to tsconfig.json paths`);\n}\n\n/**\n * Tell the user the next command is theirs to run.\n *\n * This is the seam. Everything above is prerequisite; from here the shadcn docs\n * apply verbatim, which is the entire point of not wrapping their CLI.\n *\n * WHY THIS FEATURE DECLARES cva AND lucide-react, and where the list came from.\n *\n * shadcn's registry splits dependencies across two levels. Each component item\n * (`.../new-york-v4/button.json`) declares only what that file pulls beyond the\n * baseline — for button, `radix-ui` and nothing else. Everything the baseline\n * assumes lives on the STYLE INDEX (`.../new-york-v4/index.json`), which is\n * fetched by `init` and only by `init`:\n *\n *   dependencies:    class-variance-authority, lucide-react, radix-ui\n *   devDependencies: tw-animate-css, shadcn\n *\n * We skip `init` on purpose — it would rewrite components.json and replace the\n * literal tokens with the `@theme inline` block that resolves to nothing here.\n * Skipping it is right; inheriting nothing from it was the bug. `shadcn add\n * button` exits 0 and writes `import { cva } from \"class-variance-authority\"`\n * against a package no one installed. Zero exit code, TS2307, blank page.\n *\n * `radix-ui` stays off our list: it is the one style-index dependency that is\n * ALSO declared per-component, so `add` really does install it on demand, and\n * declaring it here would pull the whole primitive set into projects using two\n * components. `shadcn` itself stays off too — it is the CLI, and the user is\n * invoking it via `npx`.\n *\n * `tw-animate-css` was checked and deliberately EXCLUDED. It is not imported by\n * any component; it is a plain stylesheet whose only entry point is the\n * `@import \"tw-animate-css\"` line that `init` writes into the CSS — and we do\n * not write that line, so the package would install and never load. Nothing\n * fails to compile or render without it. What you lose is the enter/exit\n * animation on overlay components (dialog, dropdown, tooltip, sheet): their\n * `animate-in` / `fade-in-0` classes are simply never generated, so the overlay\n * appears instantly instead of fading. That is opt-in, and the note below is how\n * a user opts in — the `@import` has to go at the TOP of app.css, next to\n * Tailwind's own, which is why this feature cannot append it to the token block.\n */\nfunction printNextStep(): void {\n  console.log(\n    `\\n${colors.green(\"✓\")} shadcn/ui prerequisites are in place. Add components with shadcn's own CLI:\\n` +\n      `  ${colors.yellowBright(\"npx shadcn@latest add button card\")}\\n` +\n      \"  Skip `shadcn init` — this feature did its job, and running it would rewrite components.json\\n\" +\n      \"  and replace the theme tokens with an `@theme inline` block that resolves to nothing here.\\n\" +\n      `  ${colors.yellowBright(\"class-variance-authority\")} and ${colors.yellowBright(\"lucide-react\")} are already installed: shadcn declares\\n` +\n      \"  them on the style index that only `init` reads, so `add` would never install them for you.\\n\" +\n      `  ${colors.yellowBright(\"radix-ui\")} (the unified package, not @radix-ui/react-*) IS declared per component,\\n` +\n      \"  so shadcn's CLI installs that one itself as each component needs it.\\n\" +\n      `  For overlay animations, add ${colors.yellowBright(\"tw-animate-css\")} and put ${colors.yellowBright('@import \"tw-animate-css\";')}\\n` +\n      \"  at the TOP of src/web/app.css, under the Tailwind import. Without it dialogs and dropdowns\\n\" +\n      \"  still work, they just appear instantly instead of animating.\",\n  );\n}\n\n/**\n * Lay the ground shadcn's CLI expects to find, and nothing more.\n *\n * Four 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 shadcn, clsx, or Tailwind.\n */\nasync function completeShadcnInstallation(_options: CommandActionData) {\n  await writeComponentsJson();\n  await writeCnUtil();\n  await appendThemeTokens();\n  await addWebPathAlias();\n  printNextStep();\n}\n\nexport const shadcnFeature: FeatureDefinition = {\n  description:\n    \"Sets up the prerequisites for shadcn/ui so `npx shadcn add <component>` works first time: components.json aliased to src/web, src/web/lib/utils.ts (cn), the design tokens in src/web/app.css, and a web/* tsconfig path. It does NOT wrap shadcn's CLI — components stay theirs to generate and yours to own.\",\n  // `tailwind` owns src/web/app.css, which the token block is appended to.\n  // Requiring it also fixes the order: the add command resolves requirements\n  // depth-first, so the stylesheet exists before this feature writes into it.\n  requires: [\"tailwind\"],\n  // Everything `shadcn init` would have installed, minus the parts their CLI\n  // genuinely does install per-component. See the note above `printNextStep`\n  // for how this list was derived and what is deliberately NOT in it.\n  dependencies: {\n    // Both are runtime dependencies of `cn`, which every generated component\n    // calls on every render — not build-time tooling.\n    clsx: \"^2.1.1\",\n    // v3 is the Tailwind v4 line; tailwind-merge v2 knows the v3 utility set and\n    // silently fails to de-duplicate against v4 class names.\n    \"tailwind-merge\": \"^3.3.1\",\n    // `cva` is imported on line 2 of the generated button — and of every other\n    // component with a `variant` prop. The registry declares it ONCE, on the\n    // style index that only `init` applies, so `shadcn add button` resolves the\n    // component's own deps, exits 0, and leaves TS2307 on a file it just wrote.\n    // Still 0.x upstream, so this caret pins to 0.7.x; expect 0.7.1 to land.\n    \"class-variance-authority\": \"^0.7.1\",\n    // Same trap, one layer further in. `components.json` declares\n    // `iconLibrary: \"lucide\"`, and dialog/select/checkbox/dropdown-menu all\n    // import `lucide-react` in their source while declaring only `radix-ui` —\n    // verified against the new-york-v4 registry items. So the CLI installs it\n    // for nobody, and the first icon-bearing component fails to resolve.\n    // Peer range covers React 19, which is what `web` brings.\n    \"lucide-react\": \"^1.34.0\",\n  },\n  onExecuting: completeShadcnInstallation,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgC3B,MAAM,aAAa;;;;;;;;;;;;;;;;;;AAmBnB,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;AAoB7B,MAAM,mBAAmB;KACpB,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqG1B,eAAe,sBAAqC;CAClD,MAAM,qBAAqB,SAAS,iBAAiB;CAErD,IAAI,MAAM,gBAAgB,kBAAkB,GAAG;EAC7C,QAAQ,IAAI,GAAG,OAAO,aAAa,iBAAiB,EAAE,6BAA6B;EAEnF;CACF;CAEA,MAAM,aAAa,oBAAoB,kBAAkB;CACzD,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,yBAAyB;AAC5D;;;;;;;;AASA,eAAe,cAA6B;CAC1C,MAAM,YAAY,QAAQ,kBAAkB;CAE5C,IAAI,MAAM,gBAAgB,SAAS,GAAG;EACpC,MAAM,UAAU,MAAM,aAAa,SAAS,CAAC,CAAC,YAAY,EAAE;EAE5D,IAAI,mCAAmC,KAAK,OAAO,GACjD,QAAQ,IAAI,GAAG,OAAO,aAAa,sBAAsB,EAAE,iCAAiC;OAE5F,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,GAAG,OAAO,aAAa,sBAAsB,EAAE,8BACtE,OAAO,aAAa,IAAI,EAAE;sFAGjC;EAGF;CACF;CAEA,MAAM,qBAAqB,QAAQ,SAAS,CAAC;CAC7C,MAAM,aAAa,WAAW,UAAU;CACxC,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,8BAA8B;AACjE;;;;;;;;;;;;;AAcA,eAAe,oBAAmC;CAChD,MAAM,UAAU,QAAQ,aAAa;CAErC,IAAI,CAAE,MAAM,gBAAgB,OAAO,GAAI;EACrC,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,GAAG,OAAO,aAAa,iBAAiB,EAAE;wJAIxE;EAEA;CACF;CAEA,MAAM,UAAU,MAAM,aAAa,OAAO;CAE1C,IAAI,QAAQ,SAAS,oBAAoB,KAAK,QAAQ,SAAS,4BAA4B,GAAG;EAC5F,QAAQ,IAAI,GAAG,OAAO,aAAa,iBAAiB,EAAE,qCAAqC;EAE3F;CACF;CAEA,MAAM,aAAa,SAAS,GAAG,QAAQ,QAAQ,EAAE,IAAI,kBAAkB;CACvE,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,+CAA+C;AAClF;;AAGA,MAAM,iBAAiB;;;;;;;;;;;;;;;AAgBvB,eAAe,kBAAiC;CAC9C,MAAM,eAAe,SAAS,eAAe;CAE7C,MAAM,0BAA0B,WAAmB;EACjD,QAAQ,IACN,GAAG,OAAO,aAAa,GAAG,EAAE,GAAG,OAAO,aAAa,eAAe,EAAE,GAAG,OAAO;IAEvE,eAAe,gGAExB;CACF;CAEA,IAAI,CAAE,MAAM,gBAAgB,YAAY,GAAI;EAC1C,uBAAuB,WAAW;EAElC;CACF;CAEA,MAAM,UAAU,MAAM,aAAa,YAAY;CAI/C,IAAI,sBAAsB,KAAK,OAAO,GAAG;EACvC,QAAQ,IAAI,GAAG,OAAO,aAAa,eAAe,EAAE,iCAAiC;EAErF;CACF;CAEA,IAAI;CAEJ,IAAI,mBAAmB,KAAK,OAAO,GACjC,OAAO,QAAQ,QAAQ,oBAAoB,aAAa,eAAe,EAAE;MACpE,IAAI,6BAA6B,KAAK,OAAO,GAClD,OAAO,QAAQ,QACb,8BACA,6BAA6B,eAAe,SAC9C;MACK;EACL,uBAAuB,2CAA2C;EAElE;CACF;CAEA,MAAM,aAAa,cAAc,IAAI;CACrC,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,SAAS,eAAe,wBAAwB;AACnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,SAAS,gBAAsB;CAC7B,QAAQ,IACN,KAAK,OAAO,MAAM,GAAG,EAAE,kFAChB,OAAO,aAAa,mCAAmC,EAAE;;IAGzD,OAAO,aAAa,0BAA0B,EAAE,OAAO,OAAO,aAAa,cAAc,EAAE;IAE3F,OAAO,aAAa,UAAU,EAAE;gCAEJ,OAAO,aAAa,gBAAgB,EAAE,WAAW,OAAO,aAAa,6BAA2B,EAAE;+DAGvI;AACF;;;;;;;;;AAUA,eAAe,2BAA2B,UAA6B;CACrE,MAAM,oBAAoB;CAC1B,MAAM,YAAY;CAClB,MAAM,kBAAkB;CACxB,MAAM,gBAAgB;CACtB,cAAc;AAChB;AAEA,MAAa,gBAAmC;CAC9C,aACE;CAIF,UAAU,CAAC,UAAU;CAIrB,cAAc;EAGZ,MAAM;EAGN,kBAAkB;EAMlB,4BAA4B;EAO5B,gBAAgB;CAClB;CACA,aAAa;AACf"}

package/esm/generations/features/shared/link-ai-package-import.mjs

@@ -0,0 +1,37 @@
+import { srcPath } from "../../../utils/paths.mjs";
+import "../../../utils/index.mjs";
+import { colors } from "@mongez/copper";
+import { fileExistsAsync, getFileAsync, putFileAsync } from "@warlock.js/fs";
+
+//#region ../core/src/generations/features/shared/link-ai-package-import.ts
+/**
+* Link a satellite AI package into src/config/ai.ts via a side-effect import.
+*
+* The satellites (@warlock.js/ai-tools, ai-panoptic, ai-workspace) augment the
+* `ai` object on import — they register their runtime surface (ai.tools / ai.mcp,
+* ai.workspace, panoptic's ai.config({ panoptic }) wiring) AND the matching TS
+* declaration-merging so ai.* members resolve. config-loader runs config/ai.ts at
+* boot, so dropping a bare `import "<specifier>";` at the top of that file is what
+* actually loads the augmentation before the ai connector applies the config.
+*
+* No-op if config/ai.ts is missing (the `ai` feature ejects it) or the import is
+* already present. Inserts right after the `warlock:ai-packages` marker when it
+* exists so the satellite imports stay grouped; otherwise prepends to the top.
+*/
+async function linkAiPackageImport(specifier) {
+	const aiConfigPath = srcPath("config/ai.ts");
+	if (!await fileExistsAsync(aiConfigPath)) return;
+	const current = await getFileAsync(aiConfigPath);
+	const importLine = `import "${specifier}";`;
+	if (current.includes(importLine)) return;
+	const marker = "// >>> warlock:ai-packages (auto-managed) >>>";
+	let next;
+	if (current.includes(marker)) next = current.replace(marker, `${marker}\n${importLine}`);
+	else next = `${importLine}\n${current}`;
+	await putFileAsync(aiConfigPath, next);
+	console.log(`${colors.green("✓")} Linked ${specifier} in src/config/ai.ts`);
+}
+
+//#endregion
+export { linkAiPackageImport };
+//# sourceMappingURL=link-ai-package-import.mjs.map

package/esm/generations/features/shared/link-ai-package-import.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-ai-package-import.mjs","names":[],"sources":["../../../../../../../../../core/src/generations/features/shared/link-ai-package-import.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { fileExistsAsync, getFileAsync, putFileAsync } from \"@warlock.js/fs\";\nimport { srcPath } from \"../../../utils\";\n\n/**\n * Link a satellite AI package into src/config/ai.ts via a side-effect import.\n *\n * The satellites (@warlock.js/ai-tools, ai-panoptic, ai-workspace) augment the\n * `ai` object on import — they register their runtime surface (ai.tools / ai.mcp,\n * ai.workspace, panoptic's ai.config({ panoptic }) wiring) AND the matching TS\n * declaration-merging so ai.* members resolve. config-loader runs config/ai.ts at\n * boot, so dropping a bare `import \"<specifier>\";` at the top of that file is what\n * actually loads the augmentation before the ai connector applies the config.\n *\n * No-op if config/ai.ts is missing (the `ai` feature ejects it) or the import is\n * already present. Inserts right after the `warlock:ai-packages` marker when it\n * exists so the satellite imports stay grouped; otherwise prepends to the top.\n */\nexport async function linkAiPackageImport(specifier: string): Promise<void> {\n  const aiConfigPath = srcPath(\"config/ai.ts\");\n\n  if (!(await fileExistsAsync(aiConfigPath))) {\n    return;\n  }\n\n  const current = await getFileAsync(aiConfigPath);\n  const importLine = `import \"${specifier}\";`;\n\n  if (current.includes(importLine)) {\n    return;\n  }\n\n  const marker = \"// >>> warlock:ai-packages (auto-managed) >>>\";\n  let next: string;\n\n  if (current.includes(marker)) {\n    next = current.replace(marker, `${marker}\\n${importLine}`);\n  } else {\n    next = `${importLine}\\n${current}`;\n  }\n\n  await putFileAsync(aiConfigPath, next);\n\n  console.log(`${colors.green(\"✓\")} Linked ${specifier} in src/config/ai.ts`);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAkBA,eAAsB,oBAAoB,WAAkC;CAC1E,MAAM,eAAe,QAAQ,cAAc;CAE3C,IAAI,CAAE,MAAM,gBAAgB,YAAY,GACtC;CAGF,MAAM,UAAU,MAAM,aAAa,YAAY;CAC/C,MAAM,aAAa,WAAW,UAAU;CAExC,IAAI,QAAQ,SAAS,UAAU,GAC7B;CAGF,MAAM,SAAS;CACf,IAAI;CAEJ,IAAI,QAAQ,SAAS,MAAM,GACzB,OAAO,QAAQ,QAAQ,QAAQ,GAAG,OAAO,IAAI,YAAY;MAEzD,OAAO,GAAG,WAAW,IAAI;CAG3B,MAAM,aAAa,cAAc,IAAI;CAErC,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,UAAU,UAAU,qBAAqB;AAC5E"}

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

@@ -0,0 +1,17 @@
+//#region ../core/src/generations/features/shared/migration-timestamp.ts
+/**
+* Build a migration filename timestamp prefix in the framework's
+* MM-DD-YYYY_HH-MM-SS form. Cascade infers a migration's createdAt from this
+* prefix and orders migrations deterministically by it. Pass `offsetSeconds` to
+* stamp sibling migrations created in the same scaffold a second apart so they
+* never collide and keep a stable relative order.
+*/
+function migrationTimestamp(offsetSeconds = 0) {
+	const now = new Date(Date.now() + offsetSeconds * 1e3);
+	const pad = (value) => String(value).padStart(2, "0");
+	return `${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${now.getFullYear()}_${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
+}
+
+//#endregion
+export { migrationTimestamp };
+//# sourceMappingURL=migration-timestamp.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,15 @@
+import { socketConfigStub } from "../stubs.mjs";
+
+//#region ../core/src/generations/features/socket.feature.ts
+const socketFeature = {
+	description: "Installs socket.io for the realtime socket server (Socket Connector)",
+	dependencies: { "socket.io": "^4.8.3" },
+	ejectConfig: {
+		content: socketConfigStub,
+		name: "socket"
+	}
+};
+
+//#endregion
+export { socketFeature };
+//# sourceMappingURL=socket.feature.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"socket.feature.mjs","names":[],"sources":["../../../../../../../../core/src/generations/features/socket.feature.ts"],"sourcesContent":["import { socketConfigStub } from \"../stubs\";\r\nimport { FeatureDefinition } from \"./types\";\r\n\r\nexport const socketFeature: FeatureDefinition = {\r\n  description: \"Installs socket.io for the realtime socket server (Socket Connector)\",\r\n  dependencies: {\r\n    \"socket.io\": \"^4.8.3\",\r\n  },\r\n  ejectConfig: {\r\n    content: socketConfigStub,\r\n    name: \"socket\",\r\n  },\r\n};\r\n"],"mappings":";;;AAGA,MAAa,gBAAmC;CAC9C,aAAa;CACb,cAAc,EACZ,aAAa,SACf;CACA,aAAa;EACX,SAAS;EACT,MAAM;CACR;AACF"}

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

@@ -0,0 +1,174 @@
+import { rootPath, srcPath } from "../../utils/paths.mjs";
+import "../../utils/index.mjs";
+import { colors } from "@mongez/copper";
+import { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "@warlock.js/fs";
+
+//#region ../core/src/generations/features/tailwind.feature.ts
+/**
+* The stylesheet entry, and the whole of Tailwind's configuration.
+*
+* Tailwind v4 is CSS-first: there is no `tailwind.config.js` and no `content`
+* globs to keep in sync with the project layout — the engine discovers the
+* templates that reach it through the bundler graph, and everything a v3 config
+* held (`theme`, `plugins`, `darkMode`) is expressed in CSS beside the import.
+* So this one file is the config, which is why the feature writes it rather
+* than an `ejectConfig` entry: `ejectConfig` lands in `src/config/*.ts`, and a
+* stylesheet that must sit in the bundler's path does not belong there.
+*/
+const appCssStub = `@import "tailwindcss";
+
+/*
+  Tailwind v4 configures itself from CSS — there is no tailwind.config.js.
+
+  Design tokens go in an @theme block, and each one becomes both a CSS variable
+  and a utility class:
+
+    @theme {
+      --color-brand: oklch(0.62 0.19 259);
+      --font-display: "Inter", sans-serif;
+    }
+
+  gives you \`bg-brand\`, \`text-brand\`, \`font-display\` and \`var(--color-brand)\`.
+
+  Plugins are imported here too — \`@plugin "@tailwindcss/typography";\` — and
+  your own non-utility CSS can simply follow this comment.
+*/
+`;
+/**
+* PostCSS rather than a Vite config file, and deliberately at the project root.
+*
+* Vite discovers `postcss.config.mjs` from the project root on its own, in the
+* dev server and in `vite build` alike, without the application owning a Vite
+* config at all. That matters here: the only app-facing Vite plugin array in
+* this framework is `webConnector({ plugins })`, which is wired into the DEV
+* server exclusively — the client build composes its own plugin list from its
+* caller. Registering `@tailwindcss/vite` there would produce styles in `dev`
+* and silently drop them from a production build, which is a worse failure than
+* any config file, because it only shows up after deploy.
+*
+* `.mjs` because a Warlock project's `package.json` is not guaranteed to set
+* `"type": "module"`, and `export default` in a `.js` file would throw in a
+* CommonJS project.
+*/
+const postcssConfigStub = `/**
+ * Tailwind v4 runs as a PostCSS plugin. Vite loads this file automatically —
+ * in dev and in build — so no Vite configuration is required.
+ *
+ * The plugin lives in its own package in v4: \`tailwindcss\` is the engine,
+ * \`@tailwindcss/postcss\` is the adapter. Naming \`tailwindcss\` here directly is
+ * the v3 spelling and will not work.
+ */
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+`;
+/**
+* Every filename Vite/PostCSS will pick up from the project root.
+*
+* Checked as a set rather than just writing our own: two PostCSS configs in one
+* directory is not a merge, it is a coin toss over which one loads, so a project
+* that already has one gets instructions instead of a second file.
+*/
+const POSTCSS_CONFIG_FILES = [
+	"postcss.config.mjs",
+	"postcss.config.js",
+	"postcss.config.cjs",
+	"postcss.config.ts",
+	"postcss.config.json",
+	".postcssrc",
+	".postcssrc.js",
+	".postcssrc.json"
+];
+/** The side-effect import that pulls the stylesheet into the bundler graph. */
+const APP_CSS_IMPORT = "import \"./app.css\";";
+/**
+* Create `src/web/app.css` — the sentinel for "this feature already ran".
+*
+* Nothing in the project template creates this file (the scaffold ships a
+* static `public/home.css` instead), so its presence means `add tailwind` has
+* been here, and its contents may since have been edited into a real design
+* system. It is never rewritten.
+*/
+async function createStylesheet() {
+	const cssFile = srcPath("web/app.css");
+	if (await fileExistsAsync(cssFile)) {
+		console.log(`${colors.yellowBright("src/web/app.css")} already exists, skipping...`);
+		return false;
+	}
+	await ensureDirectoryAsync(srcPath("web"));
+	await putFileAsync(cssFile, appCssStub);
+	console.log(`${colors.green("✓")} Created src/web/app.css`);
+	return true;
+}
+/**
+* Write `postcss.config.mjs`, unless the project already has a PostCSS config.
+*
+* An existing config is left completely alone. It is an app-owned build file
+* that may already register autoprefixer, nesting, or a CSS-modules pass, and
+* appending Tailwind to it by string surgery would be guessing at both its
+* module format and its plugin order.
+*/
+async function writePostcssConfig() {
+	for (const name of POSTCSS_CONFIG_FILES) {
+		if (!await fileExistsAsync(rootPath(name))) continue;
+		if ((await getFileAsync(rootPath(name)).catch(() => "")).includes("@tailwindcss/postcss")) console.log(`${colors.yellowBright(name)} already registers Tailwind, skipping...`);
+		else console.log(`${colors.yellowBright("!")} ${colors.yellowBright(name)} already exists — add Tailwind to it yourself:\n  plugins: { "@tailwindcss/postcss": {} }\n  Two PostCSS configs in one project is undefined behaviour, so this feature did not write a second one.`);
+		return;
+	}
+	await putFileAsync(rootPath("postcss.config.mjs"), postcssConfigStub);
+	console.log(`${colors.green("✓")} Created postcss.config.mjs`);
+}
+/**
+* Import the stylesheet from `src/web/root.tsx`.
+*
+* The root is the one module every SSR page renders through, so importing the
+* stylesheet there is what puts it in the client bundle for every route.
+*
+* `root.tsx` is guaranteed to exist by the time this runs: `requires: ["web"]`
+* makes the add command resolve `web` ahead of `tailwind` and run its
+* `onExecuting` first, and that is what creates the file. The check below is
+* therefore for a root a human has since moved or deleted — a case worth a
+* printed instruction, not a failure.
+*/
+async function importStylesheetFromRoot() {
+	const rootFile = srcPath("web/root.tsx");
+	if (!await fileExistsAsync(rootFile)) {
+		console.log(`${colors.yellowBright("!")} ${colors.yellowBright("src/web/root.tsx")} not found — add ${colors.yellowBright(APP_CSS_IMPORT)} to your application root yourself.\n  Until the stylesheet is imported from a module the bundler reaches, no Tailwind CSS is emitted.`);
+		return;
+	}
+	const current = await getFileAsync(rootFile);
+	if (/import\s+["'].*app\.css["']/.test(current)) {
+		console.log(`${colors.yellowBright("src/web/root.tsx")} already imports app.css, skipping...`);
+		return;
+	}
+	await putFileAsync(rootFile, `${APP_CSS_IMPORT}\n${current}`);
+	console.log(`${colors.green("✓")} Imported app.css in src/web/root.tsx`);
+}
+/**
+* Wire Tailwind v4 into the page layer.
+*
+* Three files, none of which needs `node_modules` to be populated: on the
+* `create-warlock` path this runs under `--no-install`, so the dependencies
+* declared below are only recorded in `package.json` and nothing here may
+* import, resolve, or execute Tailwind itself.
+*/
+async function completeTailwindInstallation(_options) {
+	await createStylesheet();
+	await writePostcssConfig();
+	await importStylesheetFromRoot();
+}
+const tailwindFeature = {
+	description: "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.",
+	requires: ["web"],
+	devDependencies: {
+		tailwindcss: "^4.1.16",
+		"@tailwindcss/postcss": "^4.1.16"
+	},
+	onExecuting: completeTailwindInstallation
+};
+
+//#endregion
+export { tailwindFeature };
+//# sourceMappingURL=tailwind.feature.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,96 @@
+import { rootPath, srcPath } from "../../utils/paths.mjs";
+import "../../utils/index.mjs";
+import { colors } from "@mongez/copper";
+import { fileExistsAsync, putFileAsync } from "@warlock.js/fs";
+
+//#region ../core/src/generations/features/test.feature.ts
+async function completeTestInstallation(options) {
+	const testGlobalSetupPath = srcPath("test-global-setup.ts");
+	if (!await fileExistsAsync(testGlobalSetupPath)) {
+		await putFileAsync(testGlobalSetupPath, `/**
+ * Global Test Setup
+ *
+ * Runs ONCE before all test workers.
+ * Starts the HTTP server for integration tests.
+ */
+import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests";
+
+export async function setup() {
+  await startHttpTestServer();
+}
+
+export async function teardown() {
+  await stopHttpTestServer();
+}
+`);
+		console.log(`${colors.green("✓")} Created src/test-global-setup.ts`);
+	}
+	const testSetupPath = srcPath("test-setup.ts");
+	if (!await fileExistsAsync(testSetupPath)) {
+		await putFileAsync(testSetupPath, `/**
+ * Test Setup - runs before EVERY test file
+ *
+ * Vitest runs setupFiles before each test file and rebuilds the module
+ * registry with it, so this pair boots and closes the test runtime once per
+ * test file.
+ *
+ * setupTest() is called with no options on purpose: an explicit connectors
+ * value outranks tests.connectors from src/config/tests.ts, so passing one
+ * here would erase your project config. Omitting it leaves the config in
+ * charge.
+ *
+ * afterAll(teardownTest) is the other half of the pair: whoever calls
+ * setupTest() owns closing it in the same runtime context.
+ */
+import { setupTest, teardownTest } from "@warlock.js/core/tests";
+import { afterAll } from "vitest";
+
+await setupTest();
+
+afterAll(teardownTest);
+`);
+		console.log(`${colors.green("✓")} Created src/test-setup.ts`);
+	}
+	const viteConfigPath = rootPath("vite.config.ts");
+	if (!await fileExistsAsync(viteConfigPath)) {
+		await putFileAsync(viteConfigPath, `import { lowerStage3Decorators } from "@warlock.js/core/vite";
+import mongezVite from "@mongez/vite";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  // lowerStage3Decorators MUST come first: it lowers native (@RegisterModel, …)
+  // decorators with esbuild before oxc / the SSR rewrite can mangle them, so
+  // decorated Cascade models load under Vitest.
+  plugins: [lowerStage3Decorators(), mongezVite()],
+  test: {
+    globalSetup: "./src/test-global-setup.ts", // HTTP server - runs once
+    setupFiles: ["./src/test-setup.ts"],       // DB/cache - runs per test file
+    environment: "node",
+    globals: false,
+    include: ["src/app/**/*.test.ts"],
+  },
+});
+`);
+		console.log(`${colors.green("✓")} Created vite.config.ts`);
+	}
+}
+const testFeature = {
+	description: "Installs warlock test for testing",
+	onExecuting: completeTestInstallation,
+	script: {
+		test: "vitest run",
+		"test:coverage": "vitest run --coverage",
+		"test:ui": "vitest --ui",
+		"test:watch": "vitest --watch"
+	},
+	devDependencies: {
+		"@mongez/vite": "^2.0.4",
+		vite: "^8.0.16",
+		vitest: "^4.1.8",
+		"@vitest/coverage-v8": "^4.1.8"
+	}
+};
+
+//#endregion
+export { testFeature };
+//# sourceMappingURL=test.feature.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"test.feature.mjs","names":[],"sources":["../../../../../../../../core/src/generations/features/test.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\r\nimport { fileExistsAsync, putFileAsync } from \"@warlock.js/fs\";\r\nimport { CommandActionData } from \"../../commands/types\";\r\nimport { rootPath, srcPath } from \"../../utils\";\r\nimport { FeatureDefinition } from \"./types\";\r\n\r\nasync function completeTestInstallation(options: CommandActionData) {\r\n  // Create test-global-setup.ts (runs once before all tests)\r\n  const testGlobalSetupPath = srcPath(\"test-global-setup.ts\");\r\n  const testGlobalSetupExists = await fileExistsAsync(testGlobalSetupPath);\r\n\r\n  if (!testGlobalSetupExists) {\r\n    await putFileAsync(\r\n      testGlobalSetupPath,\r\n      `/**\r\n * Global Test Setup\r\n *\r\n * Runs ONCE before all test workers.\r\n * Starts the HTTP server for integration tests.\r\n */\r\nimport { startHttpTestServer, stopHttpTestServer } from \"@warlock.js/core/tests\";\r\n\r\nexport async function setup() {\r\n  await startHttpTestServer();\r\n}\r\n\r\nexport async function teardown() {\r\n  await stopHttpTestServer();\r\n}\r\n`,\r\n    );\r\n    console.log(`${colors.green(\"✓\")} Created src/test-global-setup.ts`);\r\n  }\r\n\r\n  // Create test-setup.ts (runs before EVERY test file)\r\n  const testSetupPath = srcPath(\"test-setup.ts\");\r\n  const testSetupExists = await fileExistsAsync(testSetupPath);\r\n\r\n  if (!testSetupExists) {\r\n    await putFileAsync(\r\n      testSetupPath,\r\n      `/**\r\n * Test Setup - runs before EVERY test file\r\n *\r\n * Vitest runs setupFiles before each test file and rebuilds the module\r\n * registry with it, so this pair boots and closes the test runtime once per\r\n * test file.\r\n *\r\n * setupTest() is called with no options on purpose: an explicit connectors\r\n * value outranks tests.connectors from src/config/tests.ts, so passing one\r\n * here would erase your project config. Omitting it leaves the config in\r\n * charge.\r\n *\r\n * afterAll(teardownTest) is the other half of the pair: whoever calls\r\n * setupTest() owns closing it in the same runtime context.\r\n */\r\nimport { setupTest, teardownTest } from \"@warlock.js/core/tests\";\r\nimport { afterAll } from \"vitest\";\r\n\r\nawait setupTest();\r\n\r\nafterAll(teardownTest);\r\n`,\r\n    );\r\n    console.log(`${colors.green(\"✓\")} Created src/test-setup.ts`);\r\n  }\r\n\r\n  // Create vite.config.ts\r\n  const viteConfigPath = rootPath(\"vite.config.ts\");\r\n  const viteConfigExists = await fileExistsAsync(viteConfigPath);\r\n\r\n  if (!viteConfigExists) {\r\n    await putFileAsync(\r\n      viteConfigPath,\r\n      `import { lowerStage3Decorators } from \"@warlock.js/core/vite\";\r\nimport mongezVite from \"@mongez/vite\";\r\nimport { defineConfig } from \"vitest/config\";\r\n\r\nexport default defineConfig({\r\n  // lowerStage3Decorators MUST come first: it lowers native (@RegisterModel, …)\r\n  // decorators with esbuild before oxc / the SSR rewrite can mangle them, so\r\n  // decorated Cascade models load under Vitest.\r\n  plugins: [lowerStage3Decorators(), mongezVite()],\r\n  test: {\r\n    globalSetup: \"./src/test-global-setup.ts\", // HTTP server - runs once\r\n    setupFiles: [\"./src/test-setup.ts\"],       // DB/cache - runs per test file\r\n    environment: \"node\",\r\n    globals: false,\r\n    include: [\"src/app/**/*.test.ts\"],\r\n  },\r\n});\r\n`,\r\n    );\r\n    console.log(`${colors.green(\"✓\")} Created vite.config.ts`);\r\n  }\r\n}\r\n\r\nexport const testFeature: FeatureDefinition = {\r\n  description: \"Installs warlock test for testing\",\r\n  onExecuting: completeTestInstallation,\r\n  script: {\r\n    test: \"vitest run\",\r\n    \"test:coverage\": \"vitest run --coverage\",\r\n    \"test:ui\": \"vitest --ui\",\r\n    \"test:watch\": \"vitest --watch\",\r\n  },\r\n  devDependencies: {\r\n    \"@mongez/vite\": \"^2.0.4\",\r\n    vite: \"^8.0.16\",\r\n    vitest: \"^4.1.8\",\r\n    \"@vitest/coverage-v8\": \"^4.1.8\",\r\n  },\r\n};\r\n"],"mappings":";;;;;;AAMA,eAAe,yBAAyB,SAA4B;CAElE,MAAM,sBAAsB,QAAQ,sBAAsB;CAG1D,IAAI,CAAC,MAF+B,gBAAgB,mBAAmB,GAE3C;EAC1B,MAAM,aACJ,qBACA;;;;;;;;;;;;;;;CAgBF;EACA,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,kCAAkC;CACrE;CAGA,MAAM,gBAAgB,QAAQ,eAAe;CAG7C,IAAI,CAAC,MAFyB,gBAAgB,aAAa,GAErC;EACpB,MAAM,aACJ,eACA;;;;;;;;;;;;;;;;;;;;;CAsBF;EACA,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,2BAA2B;CAC9D;CAGA,MAAM,iBAAiB,SAAS,gBAAgB;CAGhD,IAAI,CAAC,MAF0B,gBAAgB,cAAc,GAEtC;EACrB,MAAM,aACJ,gBACA;;;;;;;;;;;;;;;;;CAkBF;EACA,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,wBAAwB;CAC3D;AACF;AAEA,MAAa,cAAiC;CAC5C,aAAa;CACb,aAAa;CACb,QAAQ;EACN,MAAM;EACN,iBAAiB;EACjB,WAAW;EACX,cAAc;CAChB;CACA,iBAAiB;EACf,gBAAgB;EAChB,MAAM;EACN,QAAQ;EACR,uBAAuB;CACzB;AACF"}

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

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