@warlock.js/core 5.30.0 → 5.32.0

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

@@ -1 +1 @@
-{"version":3,"file":"sitemap.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/sitemap.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { fileExistsAsync, getFileAsync, putFileAsync } from \"@warlock.js/fs\";\nimport { srcPath } from \"../../utils\";\nimport { mergeWebSitemapConfig } from \"./shared/merge-web-sitemap-config\";\nimport { type FeatureDefinition, INSTALLED_WARLOCK_VERSION } from \"./types\";\n\nconst NEXT_STEPS =\n  \"Next: set `app.publicUrl` (src/config/app.ts) or the PUBLIC_APP_URL environment \" +\n  \"variable, then flip `sitemap.enabled` to true in src/config/web.ts.\";\n\n/**\n * Ships DISABLED because a sitemap needs this application's public origin and\n * a freshly generated app has no way to know it. Two steps to turn it on:\n *\n *   1. set `app.publicUrl` in src/config/app.ts, or the PUBLIC_APP_URL\n *      environment variable;\n *   2. flip `sitemap.enabled` to true here.\n *\n * With it enabled and no origin configured, generation REFUSES rather than\n * serving absolute URLs built from a guessed host — a sitemap pointing at\n * the wrong domain is worse than one that never starts, because nothing\n * downstream reports it.\n */\nconst freshWebConfigStub = `import type { WebSitemapConfig } from \"@warlock.js/web/sitemap\";\n\nconst webConfig: { sitemap: WebSitemapConfig } = {\n  sitemap: {\n    enabled: false,\n    path: \"/sitemap.xml\",\n    defaults: { changefreq: \"weekly\", priority: 0.5 },\n  },\n};\n\nexport default webConfig;\n`;\n\n/**\n * `warlock add sitemap` writes its policy into the app's \\`src/config/web.ts\\`,\n * under the \\`sitemap\\` key — there is no \\`src/config/sitemap.ts\\` and no\n * standalone connector to register; \\`@warlock.js/web\\` (already installed via\n * the \\`web\\` requirement) reads \\`web.sitemap\\` itself.\n *\n * Creates \\`web.ts\\` when the app does not have one yet; otherwise merges a\n * \\`sitemap\\` section into whatever is already there rather than clobbering it.\n */\nasync function installSitemapConfig(): Promise<void> {\n  const configPath = srcPath(\"config/web.ts\");\n\n  if (!(await fileExistsAsync(configPath))) {\n    await putFileAsync(configPath, freshWebConfigStub);\n    console.log(`${colors.green(\"✓\")} Created src/config/web.ts with a disabled sitemap section`);\n    console.log(NEXT_STEPS);\n\n    return;\n  }\n\n  const current = await getFileAsync(configPath);\n  const merge = mergeWebSitemapConfig(current);\n\n  if (merge.status === \"already-present\") {\n    console.log(\n      `${colors.yellowBright(\"sitemap\")} already configured in src/config/web.ts, skipping...`,\n    );\n\n    return;\n  }\n\n  if (merge.status === \"unrecognised\") {\n    console.log(\n      `${colors.redBright(\"✗\")} Could not safely add a \\`sitemap\\` section to ` +\n        `${colors.yellowBright(\"src/config/web.ts\")} — its exported config object was not ` +\n        \"recognised, so nothing was written. Add it yourself:\\n\" +\n        '  sitemap: { enabled: false, path: \"/sitemap.xml\", defaults: { changefreq: \"weekly\", priority: 0.5 } },',\n    );\n\n    process.exitCode = 1;\n\n    return;\n  }\n\n  await putFileAsync(configPath, merge.next);\n  console.log(`${colors.green(\"✓\")} Added a disabled \\`sitemap\\` section to src/config/web.ts`);\n  console.log(NEXT_STEPS);\n}\n\n/** `warlock add sitemap` — runtime sitemap.xml generation, backed by the page registry. */\nexport const sitemapFeature: FeatureDefinition = {\n  description:\n    \"Installs @warlock.js/sitemap — runtime sitemap.xml generation from the page registry. \" +\n    \"Adds a disabled `sitemap` section to src/config/web.ts, creating the file if it doesn't \" +\n    \"exist yet. Requires app.publicUrl (or PUBLIC_APP_URL) to be set.\",\n  requires: [\"web\"],\n  dependencies: {\n    \"@warlock.js/sitemap\": INSTALLED_WARLOCK_VERSION,\n  },\n  onExecuting: installSitemapConfig,\n};\n"],"mappings":";;;;;;;;AAMA,MAAM,aACJ;;;;;;;;;;;;;;AAgBF,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;AAsB3B,eAAe,uBAAsC;CACnD,MAAM,aAAa,QAAQ,eAAe;CAE1C,IAAI,CAAE,MAAM,gBAAgB,UAAU,GAAI;EACxC,MAAM,aAAa,YAAY,kBAAkB;EACjD,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,2DAA2D;EAC5F,QAAQ,IAAI,UAAU;EAEtB;CACF;CAGA,MAAM,QAAQ,sBAAsB,MADd,aAAa,UAAU,CACF;CAE3C,IAAI,MAAM,WAAW,mBAAmB;EACtC,QAAQ,IACN,GAAG,OAAO,aAAa,SAAS,EAAE,sDACpC;EAEA;CACF;CAEA,IAAI,MAAM,WAAW,gBAAgB;EACnC,QAAQ,IACN,GAAG,OAAO,UAAU,GAAG,EAAE,iDACpB,OAAO,aAAa,mBAAmB,EAAE;wGAGhD;EAEA,QAAQ,WAAW;EAEnB;CACF;CAEA,MAAM,aAAa,YAAY,MAAM,IAAI;CACzC,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,2DAA2D;CAC5F,QAAQ,IAAI,UAAU;AACxB;;AAGA,MAAa,iBAAoC;CAC/C,aACE;CAGF,UAAU,CAAC,KAAK;CAChB,cAAc,EACZ,uBAAuB,0BACzB;CACA,aAAa;AACf"}
+{"version":3,"file":"sitemap.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/sitemap.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { fileExistsAsync, getFileAsync, putFileAsync } from \"../generation-fs\";\nimport { srcPath } from \"../../utils\";\nimport { mergeWebSitemapConfig } from \"./shared/merge-web-sitemap-config\";\nimport { type FeatureDefinition, INSTALLED_WARLOCK_VERSION } from \"./types\";\n\nconst NEXT_STEPS =\n  \"Next: set `app.publicUrl` (src/config/app.ts) or the PUBLIC_APP_URL environment \" +\n  \"variable, then flip `sitemap.enabled` to true in src/config/web.ts.\";\n\n/**\n * Ships DISABLED because a sitemap needs this application's public origin and\n * a freshly generated app has no way to know it. Two steps to turn it on:\n *\n *   1. set `app.publicUrl` in src/config/app.ts, or the PUBLIC_APP_URL\n *      environment variable;\n *   2. flip `sitemap.enabled` to true here.\n *\n * With it enabled and no origin configured, generation REFUSES rather than\n * serving absolute URLs built from a guessed host — a sitemap pointing at\n * the wrong domain is worse than one that never starts, because nothing\n * downstream reports it.\n */\nconst freshWebConfigStub = `import type { WebSitemapConfig } from \"@warlock.js/web/sitemap\";\n\nconst webConfig: { sitemap: WebSitemapConfig } = {\n  sitemap: {\n    enabled: false,\n    path: \"/sitemap.xml\",\n    defaults: { changefreq: \"weekly\", priority: 0.5 },\n  },\n};\n\nexport default webConfig;\n`;\n\n/**\n * `warlock add sitemap` writes its policy into the app's \\`src/config/web.ts\\`,\n * under the \\`sitemap\\` key — there is no \\`src/config/sitemap.ts\\` and no\n * standalone connector to register; \\`@warlock.js/web\\` (already installed via\n * the \\`web\\` requirement) reads \\`web.sitemap\\` itself.\n *\n * Creates \\`web.ts\\` when the app does not have one yet; otherwise merges a\n * \\`sitemap\\` section into whatever is already there rather than clobbering it.\n */\nasync function installSitemapConfig(): Promise<void> {\n  const configPath = srcPath(\"config/web.ts\");\n\n  if (!(await fileExistsAsync(configPath))) {\n    await putFileAsync(configPath, freshWebConfigStub);\n    console.log(`${colors.green(\"✓\")} Created src/config/web.ts with a disabled sitemap section`);\n    console.log(NEXT_STEPS);\n\n    return;\n  }\n\n  const current = await getFileAsync(configPath);\n  const merge = mergeWebSitemapConfig(current);\n\n  if (merge.status === \"already-present\") {\n    console.log(\n      `${colors.yellowBright(\"sitemap\")} already configured in src/config/web.ts, skipping...`,\n    );\n\n    return;\n  }\n\n  if (merge.status === \"unrecognised\") {\n    console.log(\n      `${colors.redBright(\"✗\")} Could not safely add a \\`sitemap\\` section to ` +\n        `${colors.yellowBright(\"src/config/web.ts\")} — its exported config object was not ` +\n        \"recognised, so nothing was written. Add it yourself:\\n\" +\n        '  sitemap: { enabled: false, path: \"/sitemap.xml\", defaults: { changefreq: \"weekly\", priority: 0.5 } },',\n    );\n\n    process.exitCode = 1;\n\n    return;\n  }\n\n  await putFileAsync(configPath, merge.next);\n  console.log(`${colors.green(\"✓\")} Added a disabled \\`sitemap\\` section to src/config/web.ts`);\n  console.log(NEXT_STEPS);\n}\n\n/** `warlock add sitemap` — runtime sitemap.xml generation, backed by the page registry. */\nexport const sitemapFeature: FeatureDefinition = {\n  description:\n    \"Installs @warlock.js/sitemap — runtime sitemap.xml generation from the page registry. \" +\n    \"Adds a disabled `sitemap` section to src/config/web.ts, creating the file if it doesn't \" +\n    \"exist yet. Requires app.publicUrl (or PUBLIC_APP_URL) to be set.\",\n  requires: [\"web\"],\n  dependencies: {\n    \"@warlock.js/sitemap\": INSTALLED_WARLOCK_VERSION,\n  },\n  onExecuting: installSitemapConfig,\n};\n"],"mappings":";;;;;;;;AAMA,MAAM,aACJ;;;;;;;;;;;;;;AAgBF,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;AAsB3B,eAAe,uBAAsC;CACnD,MAAM,aAAa,QAAQ,eAAe;CAE1C,IAAI,CAAE,MAAM,gBAAgB,UAAU,GAAI;EACxC,MAAM,aAAa,YAAY,kBAAkB;EACjD,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,2DAA2D;EAC5F,QAAQ,IAAI,UAAU;EAEtB;CACF;CAEA,MAAM,UAAU,MAAM,aAAa,UAAU;CAC7C,MAAM,QAAQ,sBAAsB,OAAO;CAE3C,IAAI,MAAM,WAAW,mBAAmB;EACtC,QAAQ,IACN,GAAG,OAAO,aAAa,SAAS,EAAE,sDACpC;EAEA;CACF;CAEA,IAAI,MAAM,WAAW,gBAAgB;EACnC,QAAQ,IACN,GAAG,OAAO,UAAU,GAAG,EAAE,iDACpB,OAAO,aAAa,mBAAmB,EAAE;wGAGhD;EAEA,QAAQ,WAAW;EAEnB;CACF;CAEA,MAAM,aAAa,YAAY,MAAM,IAAI;CACzC,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,2DAA2D;CAC5F,QAAQ,IAAI,UAAU;AACxB;;AAGA,MAAa,iBAAoC;CAC/C,aACE;CAGF,UAAU,CAAC,KAAK;CAChB,cAAc,EACZ,uBAAuB,0BACzB;CACA,aAAa;AACf"}

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

@@ -1,7 +1,7 @@
 import { rootPath, srcPath } from "../../utils/paths.mjs";
 import "../../utils/index.mjs";
+import { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "../generation-fs.mjs";
 import { colors } from "@mongez/copper";
-import { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from "@warlock.js/fs";
 
 //#region ../../packages/core/src/generations/features/tailwind.feature.ts
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"tailwind.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/tailwind.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { ensureDirectoryAsync, fileExistsAsync, getFileAsync, putFileAsync } from \"@warlock.js/fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport type { 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":";;;;;;;;;;;;;;;;;AAiBA,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":["../../../../../../../../../packages/core/src/generations/features/tailwind.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport {\n  ensureDirectoryAsync,\n  fileExistsAsync,\n  getFileAsync,\n  putFileAsync,\n} from \"../generation-fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport type { 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

@@ -1,8 +1,9 @@
 import { rootPath, srcPath } from "../../utils/paths.mjs";
 import "../../utils/index.mjs";
+import { recordSkippedFile } from "../generation-run.mjs";
+import { fileExistsAsync, putFileAsync } from "../generation-fs.mjs";
 import { VITE_RANGE } from "./web.feature.mjs";
 import { colors } from "@mongez/copper";
-import { fileExistsAsync, putFileAsync } from "@warlock.js/fs";
 
 //#region ../../packages/core/src/generations/features/test.feature.ts
 async function completeTestInstallation(options) {
@@ -13,11 +14,15 @@ async function completeTestInstallation(options) {
  *
  * Runs ONCE before all test workers.
  * Starts the HTTP server for integration tests.
+ *
+ * port: 0 lets the OS pick a free port, so tests run while \`warlock dev\`
+ * holds the configured one; the test helpers (testGet, actingAs, ...) are
+ * told the bound port automatically.
  */
 import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests";
 
 export async function setup() {
-  await startHttpTestServer();
+  await startHttpTestServer({ port: 0 });
 }
 
 export async function teardown() {
@@ -25,7 +30,7 @@ export async function teardown() {
 }
 `);
 		console.log(`${colors.green("✓")} Created src/test-global-setup.ts`);
-	}
+	} else recordSkippedFile(testGlobalSetupPath, "exists");
 	const testSetupPath = srcPath("test-setup.ts");
 	if (!await fileExistsAsync(testSetupPath)) {
 		await putFileAsync(testSetupPath, `/**
@@ -55,7 +60,7 @@ await setupTest({ importModule: (file) => import(file) });
 afterAll(teardownTest);
 `);
 		console.log(`${colors.green("✓")} Created src/test-setup.ts`);
-	}
+	} else recordSkippedFile(testSetupPath, "exists");
 	const viteConfigPath = rootPath("vite.config.ts");
 	if (!await fileExistsAsync(viteConfigPath)) {
 		await putFileAsync(viteConfigPath, `import { lowerStage3Decorators } from "@warlock.js/core/vite";
@@ -72,12 +77,12 @@ export default defineConfig({
     setupFiles: ["./src/test-setup.ts"],       // DB/cache - runs per test file
     environment: "node",
     globals: false,
-    include: ["src/app/**/*.test.ts"],
+    include: ["src/app/**/*.{test,spec}.ts"],
   },
 });
 `);
 		console.log(`${colors.green("✓")} Created vite.config.ts`);
-	}
+	} else recordSkippedFile(viteConfigPath, "exists");
 }
 const testFeature = {
 	description: "Installs warlock test for testing",

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

@@ -1 +1 @@
-{"version":3,"file":"test.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/test.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { fileExistsAsync, putFileAsync } from \"@warlock.js/fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport type { FeatureDefinition } from \"./types\";\nimport { VITE_RANGE } from \"./web.feature\";\n\nasync function completeTestInstallation(options: CommandActionData) {\n  // Create test-global-setup.ts (runs once before all tests)\n  const testGlobalSetupPath = srcPath(\"test-global-setup.ts\");\n  const testGlobalSetupExists = await fileExistsAsync(testGlobalSetupPath);\n\n  if (!testGlobalSetupExists) {\n    await putFileAsync(\n      testGlobalSetupPath,\n      `/**\n * Global Test Setup\n *\n * Runs ONCE before all test workers.\n * Starts the HTTP server for integration tests.\n */\nimport { startHttpTestServer, stopHttpTestServer } from \"@warlock.js/core/tests\";\n\nexport async function setup() {\n  await startHttpTestServer();\n}\n\nexport async function teardown() {\n  await stopHttpTestServer();\n}\n`,\n    );\n    console.log(`${colors.green(\"✓\")} Created src/test-global-setup.ts`);\n  }\n\n  // Create test-setup.ts (runs before EVERY test file)\n  const testSetupPath = srcPath(\"test-setup.ts\");\n  const testSetupExists = await fileExistsAsync(testSetupPath);\n\n  if (!testSetupExists) {\n    await putFileAsync(\n      testSetupPath,\n      `/**\n * Test Setup - runs before EVERY test file\n *\n * Vitest runs setupFiles before each test file and rebuilds the module\n * registry with it, so this pair boots and closes the test runtime once per\n * test file.\n *\n * setupTest() gets no connectors option on purpose: an explicit connectors\n * value outranks tests.connectors from src/config/tests.ts, so passing one\n * here would erase your project config. Omitting it leaves the config in\n * charge.\n *\n * importModule makes Warlock load your app modules (config, routes, ...)\n * through THIS file's import(), which Vitest handles. Tests and the framework\n * then share one copy of every class, so \"owner instanceof User\" works.\n *\n * afterAll(teardownTest) is the other half of the pair: whoever calls\n * setupTest() owns closing it in the same runtime context.\n */\nimport { setupTest, teardownTest } from \"@warlock.js/core/tests\";\nimport { afterAll } from \"vitest\";\n\nawait setupTest({ importModule: (file) => import(file) });\n\nafterAll(teardownTest);\n`,\n    );\n    console.log(`${colors.green(\"✓\")} Created src/test-setup.ts`);\n  }\n\n  // Create vite.config.ts\n  const viteConfigPath = rootPath(\"vite.config.ts\");\n  const viteConfigExists = await fileExistsAsync(viteConfigPath);\n\n  if (!viteConfigExists) {\n    await putFileAsync(\n      viteConfigPath,\n      `import { lowerStage3Decorators } from \"@warlock.js/core/vite\";\nimport mongezVite from \"@mongez/vite\";\nimport { defineConfig } from \"vitest/config\";\n\nexport default defineConfig({\n  // lowerStage3Decorators MUST come first: it lowers native (@RegisterModel, …)\n  // decorators with esbuild before oxc / the SSR rewrite can mangle them, so\n  // decorated Cascade models load under Vitest.\n  plugins: [lowerStage3Decorators(), mongezVite()],\n  test: {\n    globalSetup: \"./src/test-global-setup.ts\", // HTTP server - runs once\n    setupFiles: [\"./src/test-setup.ts\"],       // DB/cache - runs per test file\n    environment: \"node\",\n    globals: false,\n    include: [\"src/app/**/*.test.ts\"],\n  },\n});\n`,\n    );\n    console.log(`${colors.green(\"✓\")} Created vite.config.ts`);\n  }\n}\n\nexport const testFeature: FeatureDefinition = {\n  description: \"Installs warlock test for testing\",\n  onExecuting: completeTestInstallation,\n  script: {\n    test: \"vitest run\",\n    \"test:coverage\": \"vitest run --coverage\",\n    \"test:ui\": \"vitest --ui\",\n    \"test:watch\": \"vitest --watch\",\n  },\n  devDependencies: {\n    \"@mongez/vite\": \"^2.0.4\",\n    vite: VITE_RANGE,\n    vitest: \"^4.1.8\",\n    \"@vitest/coverage-v8\": \"^4.1.8\",\n  },\n};\n"],"mappings":";;;;;;;AAOA,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;;;;;;;;;;;;;;;;;;;;;;;;;CA0BF;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"}
+{"version":3,"file":"test.feature.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/generations/features/test.feature.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { fileExistsAsync, putFileAsync, recordSkippedFile } from \"../generation-fs\";\nimport type { CommandActionData } from \"../../commands/types\";\nimport { rootPath, srcPath } from \"../../utils\";\nimport type { FeatureDefinition } from \"./types\";\nimport { VITE_RANGE } from \"./web.feature\";\n\nasync function completeTestInstallation(options: CommandActionData) {\n  // Create test-global-setup.ts (runs once before all tests)\n  const testGlobalSetupPath = srcPath(\"test-global-setup.ts\");\n  const testGlobalSetupExists = await fileExistsAsync(testGlobalSetupPath);\n\n  if (!testGlobalSetupExists) {\n    await putFileAsync(\n      testGlobalSetupPath,\n      `/**\n * Global Test Setup\n *\n * Runs ONCE before all test workers.\n * Starts the HTTP server for integration tests.\n *\n * port: 0 lets the OS pick a free port, so tests run while \\`warlock dev\\`\n * holds the configured one; the test helpers (testGet, actingAs, ...) are\n * told the bound port automatically.\n */\nimport { startHttpTestServer, stopHttpTestServer } from \"@warlock.js/core/tests\";\n\nexport async function setup() {\n  await startHttpTestServer({ port: 0 });\n}\n\nexport async function teardown() {\n  await stopHttpTestServer();\n}\n`,\n    );\n    console.log(`${colors.green(\"✓\")} Created src/test-global-setup.ts`);\n  } else {\n    recordSkippedFile(testGlobalSetupPath, \"exists\");\n  }\n\n  // Create test-setup.ts (runs before EVERY test file)\n  const testSetupPath = srcPath(\"test-setup.ts\");\n  const testSetupExists = await fileExistsAsync(testSetupPath);\n\n  if (!testSetupExists) {\n    await putFileAsync(\n      testSetupPath,\n      `/**\n * Test Setup - runs before EVERY test file\n *\n * Vitest runs setupFiles before each test file and rebuilds the module\n * registry with it, so this pair boots and closes the test runtime once per\n * test file.\n *\n * setupTest() gets no connectors option on purpose: an explicit connectors\n * value outranks tests.connectors from src/config/tests.ts, so passing one\n * here would erase your project config. Omitting it leaves the config in\n * charge.\n *\n * importModule makes Warlock load your app modules (config, routes, ...)\n * through THIS file's import(), which Vitest handles. Tests and the framework\n * then share one copy of every class, so \"owner instanceof User\" works.\n *\n * afterAll(teardownTest) is the other half of the pair: whoever calls\n * setupTest() owns closing it in the same runtime context.\n */\nimport { setupTest, teardownTest } from \"@warlock.js/core/tests\";\nimport { afterAll } from \"vitest\";\n\nawait setupTest({ importModule: (file) => import(file) });\n\nafterAll(teardownTest);\n`,\n    );\n    console.log(`${colors.green(\"✓\")} Created src/test-setup.ts`);\n  } else {\n    recordSkippedFile(testSetupPath, \"exists\");\n  }\n\n  // Create vite.config.ts\n  const viteConfigPath = rootPath(\"vite.config.ts\");\n  const viteConfigExists = await fileExistsAsync(viteConfigPath);\n\n  if (!viteConfigExists) {\n    await putFileAsync(\n      viteConfigPath,\n      `import { lowerStage3Decorators } from \"@warlock.js/core/vite\";\nimport mongezVite from \"@mongez/vite\";\nimport { defineConfig } from \"vitest/config\";\n\nexport default defineConfig({\n  // lowerStage3Decorators MUST come first: it lowers native (@RegisterModel, …)\n  // decorators with esbuild before oxc / the SSR rewrite can mangle them, so\n  // decorated Cascade models load under Vitest.\n  plugins: [lowerStage3Decorators(), mongezVite()],\n  test: {\n    globalSetup: \"./src/test-global-setup.ts\", // HTTP server - runs once\n    setupFiles: [\"./src/test-setup.ts\"],       // DB/cache - runs per test file\n    environment: \"node\",\n    globals: false,\n    include: [\"src/app/**/*.{test,spec}.ts\"],\n  },\n});\n`,\n    );\n    console.log(`${colors.green(\"✓\")} Created vite.config.ts`);\n  } else {\n    recordSkippedFile(viteConfigPath, \"exists\");\n  }\n}\n\nexport const testFeature: FeatureDefinition = {\n  description: \"Installs warlock test for testing\",\n  onExecuting: completeTestInstallation,\n  script: {\n    test: \"vitest run\",\n    \"test:coverage\": \"vitest run --coverage\",\n    \"test:ui\": \"vitest --ui\",\n    \"test:watch\": \"vitest --watch\",\n  },\n  devDependencies: {\n    \"@mongez/vite\": \"^2.0.4\",\n    vite: VITE_RANGE,\n    vitest: \"^4.1.8\",\n    \"@vitest/coverage-v8\": \"^4.1.8\",\n  },\n};\n"],"mappings":";;;;;;;;AAOA,eAAe,yBAAyB,SAA4B;CAElE,MAAM,sBAAsB,QAAQ,sBAAsB;CAG1D,IAAI,CAAC,MAF+B,gBAAgB,mBAAmB,GAE3C;EAC1B,MAAM,aACJ,qBACA;;;;;;;;;;;;;;;;;;;CAoBF;EACA,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,kCAAkC;CACrE,OACE,kBAAkB,qBAAqB,QAAQ;CAIjD,MAAM,gBAAgB,QAAQ,eAAe;CAG7C,IAAI,CAAC,MAFyB,gBAAgB,aAAa,GAErC;EACpB,MAAM,aACJ,eACA;;;;;;;;;;;;;;;;;;;;;;;;;CA0BF;EACA,QAAQ,IAAI,GAAG,OAAO,MAAM,GAAG,EAAE,2BAA2B;CAC9D,OACE,kBAAkB,eAAe,QAAQ;CAI3C,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,OACE,kBAAkB,gBAAgB,QAAQ;AAE9C;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

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

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

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

package/esm/generations/generation-fs.mjs

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

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

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

package/esm/generations/generation-run.mjs

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

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

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