@nutin/cli 2.1.0 → 2.1.1

package/templates/base/tools/builder/builder.js.hbs

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 
 import path from 'path';
-import { print, runScript } from '../utils/index.js';
+import { print, runScript, acquireBuildLock } from '../utils/index.js';
 import { builderConfig } from './builder.config.js';
 
+// Must happen before copy-static.js wipes/recreates dist-build — a second build
+// starting mid-run (a manual build, another dev watcher instance, ...) would
+// otherwise race it. See tools/utils/build-lock.js.
+await acquireBuildLock();
+
 const scriptsDir = path.join(process.cwd(), 'tools', 'builder', 'core');
 
 print.boldHead(`\nStarting build...`);
@@ -22,8 +27,9 @@ if (builderConfig.tailwind) runScript(path.join(scriptsDir, 'styles', 'tailwind.
 
 if (builderConfig.i18n) runScript(path.join(scriptsDir, 'i18n', 'build-i18n.js'), 'Combining locales...');
 
+runScript(path.join(scriptsDir, 'prod-bundle', 'esbuild.js'), 'Running esbuild...');
+
 if (builderConfig.isProd) {
-	runScript(path.join(scriptsDir, 'prod-bundle', 'esbuild.js'), 'Running esbuild...');
 	runScript(path.join(scriptsDir, 'prod-bundle', 'hash-files.js'), 'Hashing files...');
 	runScript(path.join(scriptsDir, 'prod-bundle', 'compress-files.js'), 'Compressing files...');
 	if (builderConfig.generateSEO) runScript(path.join(scriptsDir, 'seo', 'generate-seo-files.js'), 'Generating SEO Files...');

package/templates/base/tools/builder/core/html-index/add-tags.js.hbs

@@ -1,12 +1,9 @@
 import { writeFile } from 'fs/promises';
-import { builderConfig } from '../../builder.config.js';
 
 export async function addTags(htmlContent, filePath) {
-  const scriptSrc = builderConfig.isProd ? "bundle.js" : "app/main.js";
-  
   const tags = [
     { type: 'stylesheet', href: 'main.css', position: 'head' },
-    { type: 'script', src: scriptSrc, position: 'body' }
+    { type: 'script', src: 'bundle.js', position: 'body' }
   ];
 
   let modifiedHtml = htmlContent;

package/templates/base/tools/builder/core/html-index/add-tags.test.js.hbs

@@ -22,7 +22,7 @@ describe('addTags', () => {
     const result = await addTags(html, filePath);
 
     expect(result).toBe(
-      '<html><head><title>T</title><link rel="stylesheet" href="/main.css"></head><body><script type="module" src="/app/main.js"></script></body></html>'
+      '<html><head><title>T</title><link rel="stylesheet" href="/main.css"></head><body><script type="module" src="/bundle.js"></script></body></html>'
     );
   });
 
@@ -32,7 +32,7 @@ describe('addTags', () => {
     const result = await addTags(html, filePath);
 
     expect(result).toBe(
-      '<html><link rel="stylesheet" href="/main.css"><title>T</title><body><script type="module" src="/app/main.js"></script></body></html>'
+      '<html><link rel="stylesheet" href="/main.css"><title>T</title><body><script type="module" src="/bundle.js"></script></body></html>'
     );
   });
 
@@ -42,7 +42,7 @@ describe('addTags', () => {
     const result = await addTags(html, filePath);
 
     expect(result).toBe(
-      '<html></html><link rel="stylesheet" href="/main.css"><script type="module" src="/app/main.js"></script>'
+      '<html></html><link rel="stylesheet" href="/main.css"><script type="module" src="/bundle.js"></script>'
     );
   });
 

package/templates/base/tools/builder/core/prod-bundle/esbuild.js.hbs

@@ -4,12 +4,21 @@ import { print, errorExit } from '../../../utils/index.js';
 import { PATHS } from '../app/paths.js';
 import { builderConfig } from '../../builder.config.js';
 
-const ENTRY_FILE = path.join(PATHS.tempApp, 'main.ts');
+// Prod bundles straight from the copied .ts sources (tsc runs --noEmit there);
+// dev bundles tsc's emitted .js, which is kept on disk for testin-nutin.
+const ENTRY_FILE = path.join(PATHS.tempApp, builderConfig.isProd ? 'main.ts' : 'main.js');
 const OUT_FILE = path.join(PATHS.tempSource, 'bundle.js');
 
+const DEV_OVERRIDES = {
+  minify: false,
+  sourcemap: true,
+  drop: [],
+};
+
 async function build() {
   await esbuild.build({
     ...builderConfig.esbuild,
+    ...(builderConfig.isProd ? {} : DEV_OVERRIDES),
     platform: 'browser',
     format: 'esm',
     legalComments: 'none',
@@ -17,7 +26,7 @@ async function build() {
       '.json': 'json',
     },
     define: {
-      'process.env.NODE_ENV': '"production"',
+      'process.env.NODE_ENV': builderConfig.isProd ? '"production"' : '"development"',
     },
     entryPoints: [ENTRY_FILE],
     outfile: OUT_FILE,

package/templates/base/tools/builder/core/seo/generate-seo-html.js.hbs

@@ -8,16 +8,32 @@ import { builderConfig } from '../../builder.config.js';
 import { resolveLocaleValue, valueForLangWithFallback, collectI18nSeoIssues } from './i18n-resolution.js';
 import { segmentsOf, validateMockParams, writeRouteHtml, warnForRoutesMissingSeoConfig } from './route-output.js';
 
+// og:image/twitter:image require an absolute URL for social platforms to resolve them;
+// every other absolute field (og:url, canonical) is already baseUrl-prefixed, so ogImage
+// (a repo-relative path in config/seo.json) needs the same treatment.
+function toAbsoluteUrl(urlOrPath, baseUrl) {
+  if (!urlOrPath) return urlOrPath;
+  return /^https?:\/\//.test(urlOrPath) ? urlOrPath : `${baseUrl}${urlOrPath}`;
+}
+
 async function processRoute(template, baseUrl, defaultLanguage, languages, route, bundleUrl) {
   validateMockParams(route);
 
   const routeSuffix = route.path === '/' ? '' : route.path;
 
   if (builderConfig.i18n) {
+    // Same for every language variant of this route — lets crawlers know these URLs
+    // are alternates of one page rather than duplicate/competing content. x-default
+    // points at the default language.
+    const hreflangLinks = [
+      ...languages.map((l) => ({ hreflang: l, href: `${baseUrl}/${l}${routeSuffix}/` })),
+      { hreflang: 'x-default', href: `${baseUrl}/${defaultLanguage}${routeSuffix}/` },
+    ];
+
     for (const lang of languages) {
       const title = valueForLangWithFallback(route.title, lang, defaultLanguage);
       const description = valueForLangWithFallback(route.description, lang, defaultLanguage);
-      const ogImage = valueForLangWithFallback(route.ogImage, lang, defaultLanguage);
+      const ogImage = toAbsoluteUrl(valueForLangWithFallback(route.ogImage, lang, defaultLanguage), baseUrl);
 
       const pageUrl = `${baseUrl}/${lang}${routeSuffix}`;
       const body = await renderRoute({
@@ -31,7 +47,7 @@ async function processRoute(template, baseUrl, defaultLanguage, languages, route
       });
 
       await writeRouteHtml({
-        template, lang, title, description, pageUrl, ogImage, body,
+        template, lang, title, description, pageUrl, ogImage, body, hreflangLinks,
         outputSegments: [lang, ...segmentsOf(routeSuffix)],
         routePath: route.path,
       });
@@ -39,7 +55,7 @@ async function processRoute(template, baseUrl, defaultLanguage, languages, route
   } else {
     const title = resolveLocaleValue(route.title, defaultLanguage);
     const description = resolveLocaleValue(route.description, defaultLanguage);
-    const ogImage = resolveLocaleValue(route.ogImage, defaultLanguage);
+    const ogImage = toAbsoluteUrl(resolveLocaleValue(route.ogImage, defaultLanguage), baseUrl);
 
     if (!title || !description) {
       errorExit(`Missing title or description for route "${route.path}" in seo.json`, 'generate-seo-html');

package/templates/base/tools/builder/core/seo/html-substitutions.js.hbs

@@ -14,7 +14,7 @@ export function upsertInHead(html, pattern, replacement, fullTag) {
   return html.replace('</head>', `\n    ${fullTag}\n  </head>`);
 }
 
-export function applySubstitutions(template, lang, title, description, pageUrl, ogImage) {
+export function applySubstitutions(template, lang, title, description, pageUrl, ogImage, hreflangLinks = []) {
   let html = template;
 
   // lang attribute on <html>
@@ -53,6 +53,15 @@ export function applySubstitutions(template, lang, title, description, pageUrl,
     `<meta property="og:url" content="${pageUrl}/" />`
   );
 
+  // hreflang alternates — one per active language plus x-default, so crawlers see
+  // these URLs as language variants of the same page rather than duplicate content
+  if (hreflangLinks.length > 0) {
+    const altTags = hreflangLinks
+      .map(({ hreflang, href }) => `<link rel="alternate" hreflang="${hreflang}" href="${href}" />`)
+      .join('\n    ');
+    html = html.replace('</head>', `\n    ${altTags}\n  </head>`);
+  }
+
   // og:title
   html = upsertInHead(html,
     /(<meta\s+property=["']og:title["']\s+content=)["'][^"']*["']/,
@@ -81,6 +90,20 @@ export function applySubstitutions(template, lang, title, description, pageUrl,
     `<meta name="twitter:description" content="${escape(description)}" />`
   );
 
+  // og:type
+  html = upsertInHead(html,
+    /(<meta\s+property=["']og:type["']\s+content=)["'][^"']*["']/,
+    `$1"website"`,
+    `<meta property="og:type" content="website" />`
+  );
+
+  // twitter:card — required for Twitter/X to render an image card at all
+  html = upsertInHead(html,
+    /(<meta\s+name=["']twitter:card["']\s+content=)["'][^"']*["']/,
+    `$1"summary_large_image"`,
+    `<meta name="twitter:card" content="summary_large_image" />`
+  );
+
   // og:image + twitter:image — only when explicitly provided in route config
   if (ogImage) {
     html = upsertInHead(html,

package/templates/base/tools/builder/core/seo/route-output.js.hbs

@@ -29,8 +29,8 @@ export function validateMockParams(route) {
   }
 }
 
-export async function writeRouteHtml({ template, lang, title, description, pageUrl, ogImage, body, outputSegments, routePath }) {
-  let html = applySubstitutions(template, lang, title, description, pageUrl, ogImage);
+export async function writeRouteHtml({ template, lang, title, description, pageUrl, ogImage, body, outputSegments, routePath, hreflangLinks }) {
+  let html = applySubstitutions(template, lang, title, description, pageUrl, ogImage, hreflangLinks);
 
   if (html === template) {
     errorExit(`Failed to apply any changes for ${routePath} (lang "${lang}") — index.html may be missing a </head> tag`, 'generate-seo-html');

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

@@ -28,7 +28,11 @@ export async function getAppRoutePaths(bundleUrl, lang, pageUrl) {
 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) });
+  // <main id="app"> mirrors index.html's real mount target — View defaults to mounting
+  // there (view.ts), and without it the View tree is never attached to `document`, so
+  // DomHelper.cleanupOptionalContent()'s document-wide `[data-optional]` query silently
+  // misses it, leaking raw "undefined" text for any unset optional field.
+  const { window } = parseHTML('<!doctype html><html><body><main id="app"></main></body></html>', { location: new URL(pageUrl) });
   const { trackedFetches } = installGlobals(window, {
     lang,
     mockFetch: mockFetch ?? {},

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

@@ -13,24 +13,25 @@ const scssOrigins = builderConfig.sass.paths;
 const scssPath = (origin) => path.join(stylesPath, origin);
 const stylesInput = scssOrigins.map(origin => scssPath(origin));
 const pathsToLoad = [ ...stylesInput ];
+// resolves `@use "pkg:<package>/<subpath>"` through node_modules (package exports)
+const importers = [ new sass.NodePackageImporter() ];
 
 try {
   const mainResult = await sass.compileAsync(path.join(stylesPath, 'main.scss'), {
     loadPaths: [ ...pathsToLoad ],
+    importers,
     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')
-  ];
+  const appStyles = getFilesRecursive(appInput, 'scss');
 
   for (const style of appStyles) {
     const result = await sass.compileAsync(style, {
       loadPaths: [ ...pathsToLoad ],
+      importers,
       style: 'compressed'
     })
     fs.appendFileSync(stylesOutput, result.css);

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

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
-import { spawn } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { print, runCommand } from '../utils/index.js';
 
+const isWindows = process.platform === 'win32';
+
 async function startDev() {
   console.clear();
   print.blue('🚀 Starting Dev Environment...\n');
@@ -14,22 +16,59 @@ async function startDev() {
     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 });
+  // detached: true makes each child the leader of its own process group, so its
+  // descendants (watcher.js's own `exec('{{packageManager}} run build')` included) can be
+  // killed as a group below. Without this, a shutdown that doesn't cleanly propagate
+  // SIGINT down the shell layers (backgrounded, launched by a task runner, a closed
+  // terminal tab instead of Ctrl-C, ...) leaves them running as orphans — multiple
+  // stray watcher.js processes then race each other's builds.
+  // Not on Windows: there, detached children leave the console, so Ctrl-C would no
+  // longer reach them, and negative-pid group kills aren't supported — taskkill /T
+  // walks the process tree instead.
+  const serve = spawn(['{{packageManager}}', 'run', 'serve:only', '--silent'].join(' '), { stdio: 'inherit', shell: true, detached: !isWindows });
+  const watcher = spawn(['node', 'tools/dev/watcher.js', '--silent'].join(' '), { stdio: 'inherit', shell: true, detached: !isWindows });
+
+  const children = [serve, watcher];
+  let shuttingDown = false;
+
+  function killGroup(child, signal) {
+    if (!child.pid) return;
+    if (isWindows) {
+      spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+      return;
+    }
+    try {
+      process.kill(-child.pid, signal);
+    } catch {
+      // group already gone
+    }
+  }
+
+  function shutdown(signal, exitCode = 0) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    children.forEach((child) => killGroup(child, signal));
+    process.exit(exitCode);
+  }
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
 
   serve.on('error', (err) => {
     print.boldError(`live-server failed to start: ${err.message}`);
     process.exit(1);
   });
   serve.on('close', (code) => {
+    if (shuttingDown) return;
     print.error(`live-server exited with code ${code}`);
-    process.exit(code ?? 1);
+    shutdown('SIGTERM', code ?? 1);
   });
   watcher.on('error', (err) => {
     print.boldError(`watcher failed to start: ${err.message}`);
     process.exit(1);
   });
   watcher.on('close', (code) => {
+    if (shuttingDown) return;
     print.error(`watcher exited with code ${code}`);
   });
 }

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

@@ -9,42 +9,58 @@ const watcher = chokidar.watch(['src'], {
 });
 
 let isBuilding = false;
+let pendingRebuild = false;
 let buildTimeout = null;
+let lastChangedPath = null;
+
+function runBuild() {
+  isBuilding = true;
+  pendingRebuild = false;
+
+  console.clear();
+  print.boldInfo(`\n🔄 File changed: ${path.relative(process.cwd(), lastChangedPath)}\n`);
+  print.info('\nRebuilding...');
+
+  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) {
+      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.boldBlue('Watching for changes...');
+    }
+    isBuilding = false;
+
+    // A change arrived while this build was running — it was never picked up by
+    // any debounce timer (isBuilding used to make those just silently return,
+    // dropping the change for good), so build again now instead of missing it.
+    if (pendingRebuild) runBuild();
+  });
+}
 
 watcher.on('error', (err) => {
   print.boldError(`\nWatcher error: ${err.message}`);
 });
 
 watcher.on('change', (filePath) => {
+  lastChangedPath = filePath;
+
+  if (isBuilding) {
+    pendingRebuild = true;
+    return;
+  }
+
   if (buildTimeout) {
     clearTimeout(buildTimeout);
   }
-  
-  buildTimeout = setTimeout(() => {
-    if (isBuilding) return;
-    isBuilding = true;
-
-    console.clear();
-    print.boldInfo(`\n🔄 File changed: ${path.relative(process.cwd(), filePath)}\n`);
-    print.info('\nRebuilding...');
-
-    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) {
-        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.boldBlue('Watching for changes...');
-      }
-      isBuilding = false;
-    });
-  }, 100);
+
+  buildTimeout = setTimeout(runBuild, 100);
 });
 
 watcher.on('ready', () => {

package/templates/base/tools/generator/generator.js.hbs

@@ -2,23 +2,11 @@
 
 import path from "path";
 import { allFormats, getLastWord, print, promptBoolean, errorExit } from "../utils/index.js";
-import { generateFile, appendToIndex, generateLocalesJson } from "./handle-file.js";
+import fs from "fs";
+import { generateFile, generateLocalesJson } from "./handle-file.js";
 import { serviceTemplate, componentTemplate, viewTemplate, htmlTemplate, scssTemplate, testTemplate } from "./templates/index.js";
 import nutinConfig from "../../nutin.config.js";
 
-// Constants and Setup
-const [, , rawType, rawFullPath] = process.argv;
-
-if (!rawType || !rawFullPath) {
-  showUsageAndExit("Missing arguments.");
-  process.exit(1);
-}
-
-const type = allFormats(rawType);
-const fullPath = allFormats(rawFullPath);
-const name = allFormats(getLastWord(fullPath.kebab));
-const targetPath = path.join('src', 'app', `${type.kebab}s/${fullPath.kebab}`);
-
 // Creator Mapping
 const creators = {
   service: async (name, targetPath) => {
@@ -26,7 +14,6 @@ const creators = {
     print.section(`Generating service: ${name.capitalized}`);
     try {
       generateFile({ name, targetPath, templateFn: serviceTemplate, suffix: suffix });
-      appendToIndex({ name, targetPath, suffix: suffix });
       await generateTest({ name, targetPath, suffix: suffix });
     } catch (err) {
       handleError("Failed to generate service", err);
@@ -41,7 +28,6 @@ const creators = {
       generateFile({ name, targetPath, templateFn: htmlTemplate, suffix: suffix, extension: 'html' });
       generateFile({ name, targetPath, templateFn: scssTemplate, suffix: suffix, extension: 'scss' });
       await generateLocales({ targetPath, name, isView: false });
-      appendToIndex({ name, targetPath, suffix: suffix });
       await generateTest({ name, targetPath, suffix });
     } catch (err) {
       handleError("Failed to generate component", err);
@@ -56,7 +42,6 @@ const creators = {
       generateFile({ name, targetPath, templateFn: htmlTemplate, suffix: suffix, extension: 'html' });
       generateFile({ name, targetPath, templateFn: scssTemplate, suffix: suffix, extension: 'scss' });
       await generateLocales({ targetPath, name, isView: true });
-      appendToIndex({ name, targetPath, suffix: suffix });
       await generateTest({ name, targetPath, suffix });
     } catch (err) {
       handleError("Failed to generate view", err);
@@ -64,10 +49,30 @@ const creators = {
   },
 };
 
+// Constants and Setup
+const [, , rawType, rawFullPath] = process.argv;
+
+if (!rawType || !rawFullPath) {
+  showUsageAndExit("Missing arguments.");
+  process.exit(1);
+}
+
+const type = allFormats(rawType);
+const fullPath = allFormats(rawFullPath);
+const name = allFormats(getLastWord(fullPath.kebab));
+const targetPath = path.join('src', 'app', fullPath.kebab);
+
 // Main Execution
 const create = creators[type.kebab];
 
 if (create) {
+  // Folder names carry no type suffix, so a view and a component with the same path would
+  // share one folder (and clobber each other's locales/) — refuse before writing anything.
+  if (fs.existsSync(targetPath) && fs.readdirSync(targetPath).length > 0) {
+    print.boldError(`\nA folder with this name already exists: ${targetPath}`);
+    print.warn("Pick another path, e.g. user/user-view and user/user-card.");
+    process.exit(1);
+  }
   await create(name, targetPath);
   print.boldSuccess(`\n${type.capitalized} ${name.capitalized} generated in ${targetPath}.\n`)
 } else {

package/templates/base/tools/generator/handle-file.js.hbs

@@ -1,5 +1,4 @@
 import fs from 'fs';
-import path from 'path';
 import { print, LANGUAGES } from '../utils/index.js';
 import { localeTemplate } from './templates/index.js';
 
@@ -22,27 +21,6 @@ export function generateFile({
   fs.writeFileSync(filePath, template);
 }
 
-export function appendToIndex({ name, targetPath, suffix }) {
-  const absTargetPath = path.resolve(process.cwd(), targetPath);
-
-  const parts = targetPath.split(path.sep);
-  const basePath = parts.slice(0, 3).join(path.sep);
-
-  const indexFilePath = path.join(basePath, 'index.ts');
-
-  const absFilePath = path.join(absTargetPath, `${name.kebab}.${suffix}.js`);
-  const relPath = path.relative(basePath, absFilePath).replace(/\\/g, '/');
-
-  const lineToAppend = `export * from './${relPath}';\n`;
-
-  try {
-    fs.appendFileSync(indexFilePath, lineToAppend, 'utf8');
-    print.gray(`${suffix}s/index.ts updated.`);
-  } catch (err) {
-    throw new Error(`Failed to update ${indexFilePath}: ${err.message}`, { cause: err });
-  }
-}
-
 export function generateLocalesJson({ targetPath, name, isView }) {
   const localesDir = `${targetPath}/locales`;
   fs.mkdirSync(localesDir, { recursive: true });

package/templates/base/tools/generator/handle-file.test.js.hbs

@@ -1,22 +1,19 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { generateFile, appendToIndex } from './handle-file.js';
+import { generateFile } from './handle-file.js';
 
 describe('handle-file', () => {
   let tmpDir;
-  let originalCwd;
   let exitSpy;
 
   beforeEach(() => {
     tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nutin-handle-file-'));
-    originalCwd = process.cwd();
     exitSpy = spyOn(process, 'exit').andCallFake(() => {});
   });
 
   afterEach(() => {
     exitSpy.restore();
-    process.chdir(originalCwd);
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
@@ -53,20 +50,4 @@ describe('handle-file', () => {
     expect(exitSpy.callCount).toBe(1);
     expect(exitSpy.lastCall).toEqual([1]);
   });
-
-  it('appendToIndex appends an export line to the barrel three segments up from targetPath', () => {
-    process.chdir(tmpDir);
-    const basePath = path.join('src', 'app', 'components');
-    fs.mkdirSync(basePath, { recursive: true });
-    fs.writeFileSync(path.join(basePath, 'index.ts'), "export * from './existing.js';\n");
-
-    const targetPath = path.join('src', 'app', 'components', 'widget');
-    const name = { kebab: 'widget', pascal: 'Widget', camel: 'widget', capitalized: 'Widget' };
-
-    // appendToIndex prints a "index.ts updated" log via console.info
-    silenceConsole('info', () => appendToIndex({ name, targetPath, suffix: 'component' }));
-
-    const indexContent = fs.readFileSync(path.join(basePath, 'index.ts'), 'utf8');
-    expect(indexContent).toBe("export * from './existing.js';\nexport * from './widget/widget.component.js';\n");
-  });
 });

package/templates/base/tools/utils/build-lock.js.hbs

@@ -0,0 +1,69 @@
+import * as fs from 'fs';
+import path from 'path';
+import { print } from './print.js';
+
+// Guards the whole build pipeline against concurrent invocations — e.g. a manual
+// `{{packageManager}} run build` running alongside the dev watcher's auto-rebuild, or (as actually
+// happened) multiple orphaned watcher.js processes each kicking off their own build.
+// copy-static.js starts every run by wiping and recreating dist-build; two builds
+// doing that at once corrupt each other's output (missing/non-empty dist-build,
+// merge-templates.js "has both an inline and external template" conflicts, etc).
+const LOCK_DIR = path.resolve('.build-lock');
+const STALE_MS = 5 * 60 * 1000; // a full build takes seconds — anything older is a dead leftover
+const POLL_MS = 200;
+const MAX_WAIT_MS = 2 * 60 * 1000;
+
+function tryAcquire() {
+  try {
+    fs.mkdirSync(LOCK_DIR);
+    fs.writeFileSync(path.join(LOCK_DIR, 'pid'), String(process.pid));
+    return true;
+  } catch (err) {
+    if (err.code === 'EEXIST') return false;
+    throw err;
+  }
+}
+
+function isStale() {
+  try {
+    const { mtimeMs } = fs.statSync(LOCK_DIR);
+    return Date.now() - mtimeMs > STALE_MS;
+  } catch {
+    return true; // lock vanished mid-check (released concurrently) — treat as free
+  }
+}
+
+function release() {
+  try {
+    fs.rmSync(LOCK_DIR, { recursive: true, force: true });
+  } catch {
+    // already released
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function acquireBuildLock() {
+  const start = Date.now();
+  let warned = false;
+
+  while (!tryAcquire()) {
+    if (isStale()) {
+      release();
+      continue;
+    }
+
+    if (!warned) {
+      print.boldInfo('\nAnother build is already in progress — waiting for it to finish...');
+      warned = true;
+    }
+
+    if (Date.now() - start > MAX_WAIT_MS) {
+      throw new Error(`Timed out waiting for the build lock (${LOCK_DIR}) held by another process.`);
+    }
+
+    await sleep(POLL_MS);
+  }
+
+  process.on('exit', release);
+}

package/templates/base/tools/utils/index.js.hbs

@@ -6,3 +6,4 @@ export * from './run-script.js';
 export * from './prompt-boolean.js';
 export * from './languages.js';
 export * from './error-exit.js';
+export * from './build-lock.js';

package/templates/features/docker/tools/docker/Dockerfile.template.hbs

@@ -1,5 +1,5 @@
-ARG NODE_VERSION=22.23.2
-ARG ALPINE_VERSION=3.20
+ARG NODE_VERSION=24.21.0
+ARG ALPINE_VERSION=3.24
 ARG PORT="__PORTS_PLACEHOLDER__"
 
 FROM node:${NODE_VERSION}-alpine AS builder