@nutin/cli 1.3.0 → 2.0.0

package/templates/base/tools/builder/core/seo/ssr/ssr-bundle.js.hbs

@@ -0,0 +1,54 @@
+import esbuild from 'esbuild';
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { PATHS } from '../../app/paths.js';
+import { builderConfig } from '../../../builder.config.js';
+
+const SSR_DIR = path.join(PATHS.temp, '.ssr');
+const ENTRY_FILE = path.join(PATHS.tempApp, '__ssr-entry.ts');
+const OUT_FILE = path.join(SSR_DIR, 'ssr-bundle.mjs');
+
+const ENTRY_CONTENT = `export { appRoutes } from './routes.js';
+export { I18nService, Service, registerPipes } from '../core/index.js';
+export { RouteGuardsManager } from '../core/services/router/helpers/route-guard-manager.helper.js';
+`;
+
+/**
+ * Bundles a synthetic entry (re-exporting appRoutes + I18nService/Service) targeting Node,
+ * so generate-seo-html.js can import it and render real Views in a linkedom environment.
+ * Written outside dist-build/src so hash-files.js/compress-files.js never see it.
+ */
+export async function buildSsrBundle() {
+  fs.mkdirSync(SSR_DIR, { recursive: true });
+  fs.writeFileSync(ENTRY_FILE, ENTRY_CONTENT, 'utf-8');
+
+  try {
+    await esbuild.build({
+      ...builderConfig.esbuild,
+      platform: 'node',
+      format: 'esm',
+      target: ['node22'],
+      minify: false,
+      drop: [],
+      legalComments: 'none',
+      loader: {
+        '.json': 'json',
+      },
+      define: {
+        'process.env.NODE_ENV': '"production"',
+      },
+      entryPoints: [ENTRY_FILE],
+      outfile: OUT_FILE,
+      keepNames: true,
+    });
+  } finally {
+    fs.rmSync(ENTRY_FILE, { force: true });
+  }
+
+  return pathToFileURL(OUT_FILE).href;
+}
+
+export function cleanupSsrBundle() {
+  fs.rmSync(SSR_DIR, { recursive: true, force: true });
+}

package/templates/base/tools/builder/core/seo/ssr/ssr-polyfills.js.hbs

@@ -0,0 +1,132 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Installs the minimum browser globals the framework's own base classes touch
+ * unconditionally (Service's `beforeunload` listener, I18n's `navigator`/`window.location`
+ * reads), plus a couple of cheap defensive stubs (matchMedia) for common patterns
+ * downstream projects add (e.g. dark-mode toggles).
+ *
+ * Returns `trackedFetches`, the in-flight promises served by the fetch shim during this
+ * render — ssr-render.js awaits these before capturing markup, to let any resulting
+ * fetch-driven re-render (via `listenToRenderEvents`) complete first.
+ */
+function setGlobal(target, key, value) {
+  try {
+    Object.defineProperty(target, key, { value, writable: true, configurable: true, enumerable: true });
+  } catch (err) {
+    // Object.defineProperty throws a TypeError for a genuinely non-configurable
+    // property — skip it and let whatever Node/linkedom already provides stand.
+    // Anything else is unexpected and shouldn't be silently swallowed.
+    if (!(err instanceof TypeError)) throw err;
+  }
+}
+
+const KNOWN_DOM_GLOBALS = [
+  'document', 'customElements',
+  'Node', 'Element', 'HTMLElement', 'HTMLDocument',
+  'HTMLInputElement', 'HTMLTextAreaElement', 'HTMLImageElement',
+  'HTMLMediaElement', 'HTMLSourceElement', 'HTMLAnchorElement',
+  'HTMLButtonElement', 'HTMLFormElement', 'HTMLSelectElement',
+  'HTMLOptionElement', 'HTMLTemplateElement', 'HTMLStyleElement',
+  'HTMLScriptElement', 'HTMLLinkElement', 'HTMLMetaElement',
+  'HTMLTitleElement', 'HTMLHeadElement', 'HTMLBodyElement',
+  'HTMLHtmlElement', 'HTMLLabelElement', 'HTMLSpanElement',
+  'HTMLDivElement', 'HTMLUListElement', 'HTMLOListElement',
+  'HTMLLIElement', 'HTMLTableElement', 'HTMLParagraphElement',
+  'HTMLHeadingElement', 'HTMLIFrameElement',
+  'SVGElement', 'Text', 'Comment', 'DocumentFragment', 'DocumentType',
+  'Event', 'CustomEvent', 'MutationObserver', 'NodeFilter', 'NodeList',
+  'DOMParser', 'XMLSerializer', 'Attr',
+];
+
+function createMemoryStorage() {
+  const store = new Map();
+  return {
+    getItem: (key) => (store.has(key) ? store.get(key) : null),
+    setItem: (key, value) => { store.set(key, String(value)); },
+    removeItem: (key) => { store.delete(key); },
+    clear: () => { store.clear(); },
+    key: (index) => Array.from(store.keys())[index] ?? null,
+    get length() { return store.size; },
+  };
+}
+
+export function installGlobals(window, { lang, mockFetch = {}, localesDir } = {}) {
+  for (const key of Object.getOwnPropertyNames(window)) {
+    setGlobal(globalThis, key, window[key]);
+  }
+  for (const key of KNOWN_DOM_GLOBALS) {
+    if (typeof window[key] !== 'undefined') setGlobal(globalThis, key, window[key]);
+  }
+  setGlobal(globalThis, 'window', window);
+
+  const navigatorStub = { language: lang, userAgent: 'nutin-ssr' };
+  setGlobal(globalThis, 'navigator', navigatorStub);
+  setGlobal(window, 'navigator', navigatorStub);
+
+  // linkedom doesn't implement localStorage/sessionStorage at all
+  // I18n's savePreferences()/getPreferences() need it.
+  const localStorageStub = createMemoryStorage();
+  setGlobal(globalThis, 'localStorage', localStorageStub);
+  setGlobal(window, 'localStorage', localStorageStub);
+  const sessionStorageStub = createMemoryStorage();
+  setGlobal(globalThis, 'sessionStorage', sessionStorageStub);
+  setGlobal(window, 'sessionStorage', sessionStorageStub);
+
+  const matchMediaStub = (query) => ({
+    matches: false,
+    media: query,
+    addEventListener() {},
+    removeEventListener() {},
+    addListener() {},
+    removeListener() {},
+    dispatchEvent: () => false,
+  });
+  setGlobal(globalThis, 'matchMedia', matchMediaStub);
+  setGlobal(window, 'matchMedia', matchMediaStub);
+
+  const trackedFetches = [];
+
+  const fetchShim = (input) => {
+    const url = typeof input === 'string' ? input : input?.url;
+    const promise = resolveFetch(url, { mockFetch, localesDir });
+    trackedFetches.push(promise);
+    return promise;
+  };
+  setGlobal(globalThis, 'fetch', fetchShim);
+  setGlobal(window, 'fetch', fetchShim);
+
+  return { trackedFetches };
+}
+
+async function resolveFetch(url, { mockFetch, localesDir }) {
+  if (Object.prototype.hasOwnProperty.call(mockFetch, url)) {
+    return jsonResponse(mockFetch[url]);
+  }
+
+  const localeMatch = /^\/locales\/([a-zA-Z-]+)\.json$/.exec(url ?? '');
+  if (localeMatch) {
+    const filePath = path.join(localesDir, `${localeMatch[1]}.json`);
+    if (fs.existsSync(filePath)) {
+      const body = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      return jsonResponse(body);
+    }
+    // No translations authored for this locale yet — a normal early-project state, not an error.
+    return jsonResponse({});
+  }
+
+  throw new Error(
+    `Unexpected fetch("${url}") during SSR — no "mockFetch" entry for this endpoint and it isn't a ` +
+    `/locales/*.json request. Add a "mockFetch" entry for this route in config/seo.json if this is intentional.`
+  );
+}
+
+function jsonResponse(body) {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  };
+}

package/templates/base/tools/builder/core/seo/ssr/ssr-render.js.hbs

@@ -0,0 +1,95 @@
+import { parseHTML } from 'linkedom';
+import path from 'path';
+import { PATHS } from '../../app/paths.js';
+import { installGlobals } from './ssr-polyfills.js';
+import { print } from '../../../../utils/index.js';
+
+let renderIndex = 0;
+
+/**
+ * Reads the real app's route paths (the keys of `appRoutes`) without rendering anything —
+ * used to warn about app routes that have no matching config/seo.json entry.
+ */
+export async function getAppRoutePaths(bundleUrl, lang, pageUrl) {
+  // Same reasoning as renderRoute() below: I18n's getLocaleFromUrl() reads
+  // window.location.pathname, so a location-less window crashes as soon as the
+  // bundle's module-load side effects instantiate I18n.getInstance().
+  const { window } = parseHTML('<!doctype html><html><body></body></html>', { location: new URL(pageUrl) });
+  installGlobals(window, { lang });
+  const bundle = await import(`${bundleUrl}?ssr=routes-check`);
+  return Object.keys(bundle.appRoutes);
+}
+
+/**
+ * Renders one (route, lang) pair by instantiating the real View via appRoutes and calling
+ * .render(), returning the resulting real markup. Fresh linkedom window + cache-busted
+ * dynamic import per call, so no singleton state (I18nService, etc.) leaks between renders.
+ */
+export async function renderRoute({ bundleUrl, appRoutesKey, mockParams, mockFetch, lang, pageUrl, i18nEnabled }) {
+  // Passing a real URL instance as `location` gives `.pathname`/`.href`
+  // which is what I18n's getLocaleFromUrl() actually reads.
+  const { window } = parseHTML('<!doctype html><html><body></body></html>', { location: new URL(pageUrl) });
+  const { trackedFetches } = installGlobals(window, {
+    lang,
+    mockFetch: mockFetch ?? {},
+    localesDir: path.join(PATHS.tempSource, 'locales'),
+  });
+
+  let Service;
+  let constructorName = appRoutesKey;
+
+  try {
+    const bundle = await import(`${bundleUrl}?ssr=${renderIndex++}`);
+    ({ Service } = bundle);
+    const { appRoutes, I18nService, RouteGuardsManager, registerPipes } = bundle;
+
+    const routeConfig = appRoutes[appRoutesKey];
+    if (!routeConfig) {
+      throw new Error(
+        `No appRoutes entry found for "${appRoutesKey}" — check that config/seo.json's route "path" ` +
+        `matches a real key in src/app/routes.ts.`
+      );
+    }
+
+    registerPipes();
+
+    if (i18nEnabled) await I18nService.setCurrentLanguage(lang);
+
+    const viewConstructor = RouteGuardsManager.getViewConstructor(routeConfig);
+    const view = viewConstructor();
+    constructorName = view.constructor.name;
+
+    if (mockParams) view.setRouteParams(mockParams);
+
+    const element = view.render();
+
+    await Promise.all(trackedFetches);
+    await Promise.resolve();
+
+    return element.outerHTML;
+  } catch (err) {
+    throw new Error(
+      `[ssr] Failed to render route "${appRoutesKey}" (lang "${lang}", view "${constructorName}"): ${err.message}${hintForError(err)}`,
+      { cause: err }
+    );
+  } finally {
+    if (Service) {
+      try {
+        await Service.destroyAll();
+      } catch (cleanupErr) {
+        print.grayError(`[ssr] destroyAll cleanup failed: ${cleanupErr.message}`);
+      }
+    }
+  }
+}
+
+function hintForError(err) {
+  if (err instanceof ReferenceError && /is not defined$/.test(err.message)) {
+    return (
+      `\n  Hint: this usually means the component tree touches an unguarded browser global ` +
+      `(e.g. "window", "navigator", "matchMedia") that isn't polyfilled for SSR — see ` +
+      `tools/builder/core/ssr/ssr-polyfills.js.`
+    );
+  }
+  return '';
+}

package/templates/base/tools/builder/core/styles/sass.js.hbs

@@ -0,0 +1,40 @@
+import * as sass from 'sass';
+import * as fs from 'fs';
+import path from 'path';
+import { getFilesRecursive, print, errorExit } from '../../../utils/index.js';
+import { PATHS } from '../app/paths.js';
+import { builderConfig } from '../../builder.config.js';
+
+const stylesOutput = path.join(PATHS.tempSource, 'main.css');
+
+// global styles (partials)
+const stylesPath = path.join(PATHS.source, 'styles');
+const scssOrigins = builderConfig.sass.paths;
+const scssPath = (origin) => path.join(stylesPath, origin);
+const stylesInput = scssOrigins.map(origin => scssPath(origin));
+const pathsToLoad = [ ...stylesInput ];
+
+try {
+  const mainResult = await sass.compileAsync(path.join(stylesPath, 'main.scss'), {
+    loadPaths: [ ...pathsToLoad ],
+    style: 'compressed'
+  });
+  fs.writeFileSync(stylesOutput, mainResult.css);
+
+  // features styles
+  const appInput = path.join(PATHS.source, 'app');
+  const appStyles = [
+    ...getFilesRecursive(path.join(appInput, 'components'), 'scss'),
+    ...getFilesRecursive(path.join(appInput, 'views'), 'scss')
+  ];
+
+  for (const style of appStyles) {
+    const result = await sass.compileAsync(style, {
+      loadPaths: [ ...pathsToLoad ],
+      style: 'compressed'
+    })
+    fs.appendFileSync(stylesOutput, result.css);
+  }
+} catch (err) {
+  errorExit(err, 'sass');
+}

package/templates/base/tools/builder/core/styles/tailwind.js.hbs

@@ -0,0 +1,84 @@
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import path from 'path';
+import { print, runCommand, promptBoolean, errorExit } from '../../../utils/index.js';
+import { PATHS } from '../app/paths.js';
+import { builderConfig } from '../../builder.config.js';
+
+const REQUIRED_DEPS = [
+  { name: 'tailwindcss', version: '^4.3.0' },
+  { name: '@tailwindcss/cli', version: '^4.3.0' },
+];
+
+const isInstalled = (depName) => fs.existsSync(path.join(process.cwd(), 'node_modules', depName, 'package.json'));
+
+const getPackageManager = () => {
+  if (fs.existsSync(path.join(process.cwd(), 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(process.cwd(), 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(process.cwd(), 'bun.lock')) || fs.existsSync(path.join(process.cwd(), 'bun.lockb'))) return 'bun';
+  return 'npm';
+};
+
+const getInstallCommand = (packageManager, deps) => {
+  const pkgList = deps.map(dep => `${dep.name}@${dep.version}`).join(' ');
+  switch (packageManager) {
+    case 'yarn': return `yarn add -D ${pkgList}`;
+    case 'pnpm': return `pnpm add -D ${pkgList}`;
+    case 'bun': return `bun add -D ${pkgList}`;
+    default: return `npm install -D ${pkgList}`;
+  }
+};
+
+const missingDeps = REQUIRED_DEPS.filter(dep => !isInstalled(dep.name));
+
+if (missingDeps.length) {
+  if (builderConfig.isProd) {
+    errorExit('Tailwind CSS is enabled (tailwind: true) but its dependencies are missing.\nRun "npm install" before rebuilding');
+  }
+  const packageManager = getPackageManager();
+  const installCommand = getInstallCommand(packageManager, missingDeps);
+
+  print.warn('Tailwind CSS is enabled (tailwind: true) but its dependencies are missing.');
+  print.gray('Required packages:');
+  missingDeps.forEach(dep => print.gray(`  - ${dep.name}@${dep.version}`));
+
+  let shouldInstall = true;
+  if (process.stdin.isTTY) {
+    shouldInstall = await promptBoolean('Install them now?');
+  } else {
+    print.gray(`Non-interactive shell detected. Installing automatically: ${installCommand}`);
+  }
+
+  if (!shouldInstall) {
+    print.boldError(`Aborting. Run manually: ${installCommand}`);
+    process.exit(1);
+  }
+
+  const [command, ...args] = installCommand.split(' ');
+  try {
+    await runCommand(command, args);
+  } catch (err) {
+    errorExit(err, 'tailwind-install');
+  }
+}
+
+const twBin = path.join(process.cwd(), 'node_modules', '.bin', 'tailwindcss');
+const input = path.join(PATHS.source, 'styles', 'tailwind.css');
+const output = path.join(PATHS.tempSource, 'tw-out.css');
+const mainCss = path.join(PATHS.tempSource, 'main.css');
+
+const args = ['-i', input, '-o', output, '--silent'];
+if (builderConfig.isProd) args.push('--minify');
+
+try {
+  execFileSync(twBin, args, { stdio: 'inherit' });
+} catch (err) {
+  errorExit(err, 'tailwind');
+}
+
+// Tailwind's @layer blocks always lose to unlayered SCSS in the cascade regardless
+// of order, so prepending here is only for readable file ordering, not precedence.
+const tailwindCss = fs.readFileSync(output, 'utf-8');
+const existingCss = fs.readFileSync(mainCss, 'utf-8');
+fs.writeFileSync(mainCss, tailwindCss + '\n' + existingCss);
+fs.unlinkSync(output);

package/templates/base/tools/dev/dev-serve.js.hbs

@@ -1,32 +1,40 @@
 #!/usr/bin/env node
 
+import { spawn } from 'child_process';
 import { print, runCommand } from '../utils/index.js';
 
 async function startDev() {
-  try {
-    console.clear();
-    print.boldHead('🚀 Starting Dev Environment...');
-
-    await runCommand('{{packageManager}}', ['run', 'build']);
-
-    const { serve, watcher } = await Promise.all([
-      runCommand('{{packageManager}}', ['run', 'serve:only']),
-      runCommand('node', ['tools/dev/watcher.js'])
-    ]);
+  console.clear();
+  print.blue('🚀 Starting Dev Environment...\n');
 
-    serve.on('close', (code) => {
-      print.error(`live-server exited with code ${code}`);
-      process.exit(code);
-    });
-    watcher.on('close', (code) => {
-      print.error(`watcher exited with code ${code}`);
-    });
+  try {
+    await runCommand('{{packageManager}}', ['run', 'build', '--silent']);
   } catch (err) {
     print.boldError(`Dev startup failed: ${err.message}`);
+    process.exit(1);
   }
+
+  const serve = spawn(['{{packageManager}}', 'run', 'serve:only', '--silent'].join(' '), { stdio: 'inherit', shell: true });
+  const watcher = spawn(['node', 'tools/dev/watcher.js', '--silent'].join(' '), { stdio: 'inherit', shell: true });
+
+  serve.on('error', (err) => {
+    print.boldError(`live-server failed to start: ${err.message}`);
+    process.exit(1);
+  });
+  serve.on('close', (code) => {
+    print.error(`live-server exited with code ${code}`);
+    process.exit(code ?? 1);
+  });
+  watcher.on('error', (err) => {
+    print.boldError(`watcher failed to start: ${err.message}`);
+    process.exit(1);
+  });
+  watcher.on('close', (code) => {
+    print.error(`watcher exited with code ${code}`);
+  });
 }
 
 startDev().catch((err) => {
   print.boldError(`Unexpected error: ${err.message}`);
-  exit(1);
+  process.exit(1);
 });

package/templates/base/tools/dev/serve.js.hbs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import liveServer from 'live-server';
+import { print } from '../utils/index.js';
 
 const params = {
   port: 9090,
@@ -20,4 +21,13 @@ const params = {
   ]
 };
 
-liveServer.start(params);
+try {
+  liveServer.start(params);
+} catch (err) {
+  if (err.code === 'EADDRINUSE') {
+    print.boldError(`Port ${params.port} is already in use — stop the process using it or change the dev port.`);
+  } else {
+    print.boldError(`live-server failed to start: ${err.message}`);
+  }
+  process.exit(1);
+}

package/templates/base/tools/dev/watcher.js.hbs

@@ -11,6 +11,10 @@ const watcher = chokidar.watch(['src'], {
 let isBuilding = false;
 let buildTimeout = null;
 
+watcher.on('error', (err) => {
+  print.boldError(`\nWatcher error: ${err.message}`);
+});
+
 watcher.on('change', (filePath) => {
   if (buildTimeout) {
     clearTimeout(buildTimeout);
@@ -24,15 +28,19 @@ watcher.on('change', (filePath) => {
     print.boldInfo(`\n🔄 File changed: ${path.relative(process.cwd(), filePath)}\n`);
     print.info('\nRebuilding...');
 
-    const command = '{{packageManager}} run build';
-    
-    exec(command, (err, stdout, stderr) => {
+    const command = '{{packageManager}} run build --silent';
+
+    exec(command, { maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
       if (stdout) process.stdout.write(stdout);
       if (stderr) process.stderr.write(stderr);
       if (err) {
-        print.error(`\n❌ Build failed: ${err.message}`);
+        if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+          print.boldError(`\nBuild output exceeded the buffer size — raise maxBuffer in tools/dev/watcher.js.`);
+        } else {
+          print.boldError(`\nBuild failed: ${err.message}`);
+        }
       } else {
-        print.boldHead('Watching for changes...');
+        print.boldBlue('Watching for changes...');
       }
       isBuilding = false;
     });
@@ -40,5 +48,5 @@ watcher.on('change', (filePath) => {
 });
 
 watcher.on('ready', () => {
-  print.boldHead('\nWatching for changes...\n');
+  print.boldBlue('Watching for changes...');
 });