@nutin/cli 2.1.1 → 3.0.0

package/templates/base/tools/testin-nutin/watch-tests.js.hbs

@@ -1,37 +1,62 @@
 import chokidar from 'chokidar';
 import { exec } from 'child_process';
 import path from 'path';
-import { print } from './core/index.js'
+import { print } from './core/index.js';
+import config from '#root/nutin.config.js';
 
-const watcher = chokidar.watch(['src', 'test', 'unit', 'e2e'], {
+// Tests import the build output (dist/), so every run rebuilds first.
+const COMMAND = '{{packageManager}} run testin-nutin';
+
+const watched = ['src'];
+if (config.testinNutin.includeTools) watched.push('tools');
+
+const watcher = chokidar.watch(watched, {
   ignored: /(^|[/\\])\../,
   persistent: true,
+  ignoreInitial: true,
 });
 
-print.boldHead('Watching for test changes...')
+let isRunning = false;
+let pendingRun = false;
+let runTimeout = null;
+let lastChangedPath = null;
+
+function runTests() {
+  isRunning = true;
+  pendingRun = false;
+
+  console.clear();
+  print.boldInfo(`\n🔄 File changed: ${path.relative(process.cwd(), lastChangedPath)}\n`);
+
+  exec(COMMAND, { maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+    if (stdout) process.stdout.write(stdout);
+    if (stderr) process.stderr.write(stderr);
+    if (err) print.boldError(`\nTest run failed: ${err.message}`);
+    print.boldHead('Watching for test changes...');
+    isRunning = false;
+
+    // A change arrived mid-run — run again instead of dropping it.
+    if (pendingRun) runTests();
+  });
+}
 
 watcher.on('error', (err) => {
   print.boldError(`\nWatcher error: ${err.message}`);
 });
 
-let isRunning = false;
-let runTimeout = null;
+watcher.on('all', (event, filePath) => {
+  if (!['add', 'change', 'unlink'].includes(event)) return;
+  lastChangedPath = filePath;
 
-watcher.on('change', (filePath) => {
-  if (runTimeout) clearTimeout(runTimeout);
+  if (isRunning) {
+    pendingRun = true;
+    return;
+  }
 
-  runTimeout = setTimeout(() => {
-    if (isRunning) return;
-    isRunning = true;
-
-    console.clear();
-    print.boldInfo(`\n🔄 File changed: ${path.relative(process.cwd(), filePath)}\n`);
+  if (runTimeout) clearTimeout(runTimeout);
+  runTimeout = setTimeout(runTests, 100);
+});
 
-    exec('node --experimental-modules testin-nutin/runner.js', { maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
-      if (stdout) process.stdout.write(stdout);
-      if (stderr) process.stderr.write(stderr);
-      if (err) print.boldError(`\nTest run failed: ${err.message}`);
-      isRunning = false;
-    });
-  }, 100);
+watcher.on('ready', () => {
+  print.boldHead('Watching for test changes...');
 });

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

@@ -25,12 +25,32 @@ function tryAcquire() {
 }
 
 function isStale() {
+  let mtimeMs;
   try {
-    const { mtimeMs } = fs.statSync(LOCK_DIR);
-    return Date.now() - mtimeMs > STALE_MS;
+    ({ mtimeMs } = fs.statSync(LOCK_DIR));
   } catch {
     return true; // lock vanished mid-check (released concurrently) — treat as free
   }
+  if (Date.now() - mtimeMs > STALE_MS) return true;
+  return isHolderDead();
+}
+
+// A build killed hard (kill -9, a crash) never releases — free the lock right away
+// when the pid that wrote it is gone instead of waiting out STALE_MS.
+function isHolderDead() {
+  let pid;
+  try {
+    pid = Number(fs.readFileSync(path.join(LOCK_DIR, 'pid'), 'utf-8'));
+  } catch {
+    return false; // pid not written yet (holder is mid-acquire) — not provably dead
+  }
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (err) {
+    return err.code === 'ESRCH';
+  }
 }
 
 function release() {
@@ -66,4 +86,12 @@ export async function acquireBuildLock() {
   }
 
   process.on('exit', release);
+  // 'exit' doesn't fire when a signal terminates the process (Ctrl-C, dev-serve's
+  // group kill), so release explicitly there too, then exit the way the signal would have.
+  for (const [signal, code] of [['SIGINT', 130], ['SIGTERM', 143], ['SIGHUP', 129]]) {
+    process.once(signal, () => {
+      release();
+      process.exit(code);
+    });
+  }
 }

package/templates/base/tools/utils/ensure-deps.js.hbs

@@ -0,0 +1,72 @@
+import fs from 'fs';
+import path from 'path';
+import { print } from './print.js';
+import { errorExit } from './error-exit.js';
+import { runCommand } from './run-command.js';
+import { promptBoolean } from './prompt-boolean.js';
+
+export function isInstalled(depName) {
+  return fs.existsSync(path.join(process.cwd(), 'node_modules', depName, 'package.json'));
+}
+
+export function detectPackageManager() {
+  const has = (file) => fs.existsSync(path.join(process.cwd(), file));
+  if (has('pnpm-lock.yaml')) return 'pnpm';
+  if (has('yarn.lock')) return 'yarn';
+  if (has('bun.lock') || has('bun.lockb')) return 'bun';
+  return 'npm';
+}
+
+export function getDevInstallArgs(packageManager, deps) {
+  const pkgList = deps.map((dep) => `${dep.name}@${dep.version}`);
+  return packageManager === 'npm'
+    ? ['npm', ['install', '-D', ...pkgList]]
+    : [packageManager, ['add', '-D', ...pkgList]];
+}
+
+// builder.js forwards -y/--yes through the env, since runScript doesn't forward argv.
+function assumeYes() {
+  return process.env.NUTIN_ASSUME_YES === '1' || process.argv.includes('-y') || process.argv.includes('--yes');
+}
+
+/**
+ * Makes sure an opt-in feature's devDependencies are installed before its build step
+ * imports them. Prod builds never install. Dev builds ask on a TTY; elsewhere (CI, the
+ * dev watcher) they only install with -y/--yes, never silently.
+ */
+export async function ensureDeps({ feature, deps, isProd, origin }) {
+  const missing = deps.filter((dep) => !isInstalled(dep.name));
+  if (!missing.length) return;
+
+  const [command, args] = getDevInstallArgs(detectPackageManager(), missing);
+  const installCommand = [command, ...args].join(' ');
+
+  if (isProd) {
+    errorExit(`${feature} is enabled but its dependencies are missing.\nRun "${installCommand}" before rebuilding.`, origin);
+  }
+
+  print.warn(`${feature} is enabled but its dependencies are missing.`);
+  print.gray('Required packages:');
+  missing.forEach((dep) => print.gray(`  - ${dep.name}@${dep.version}`));
+
+  let shouldInstall;
+  if (assumeYes()) {
+    print.gray(`-y/--yes passed. Installing automatically: ${installCommand}`);
+    shouldInstall = true;
+  } else if (process.stdin.isTTY) {
+    shouldInstall = await promptBoolean('Install them now?');
+  } else {
+    errorExit(`Non-interactive shell detected. Run "${installCommand}", or rebuild with "-- -y" to install automatically.`, origin);
+  }
+
+  if (!shouldInstall) {
+    print.boldError(`Aborting. Run manually: ${installCommand}`);
+    process.exit(1);
+  }
+
+  try {
+    await runCommand(command, args);
+  } catch (err) {
+    errorExit(err, `${origin}-install`);
+  }
+}

package/templates/base/tools/utils/ensure-deps.test.js.hbs

@@ -0,0 +1,17 @@
+import { isInstalled, getDevInstallArgs } from './ensure-deps.js';
+
+describe('ensure-deps', () => {
+  it('getDevInstallArgs uses "install -D" for npm and "add -D" for the others', () => {
+    const deps = [{ name: 'a', version: '^1.0.0' }, { name: '@scope/b', version: '^2.0.0' }];
+
+    expect(getDevInstallArgs('npm', deps)).toEqual(['npm', ['install', '-D', 'a@^1.0.0', '@scope/b@^2.0.0']]);
+    expect(getDevInstallArgs('pnpm', deps)).toEqual(['pnpm', ['add', '-D', 'a@^1.0.0', '@scope/b@^2.0.0']]);
+    expect(getDevInstallArgs('yarn', deps)[1][0]).toBe('add');
+    expect(getDevInstallArgs('bun', deps)[1][0]).toBe('add');
+  });
+
+  it('isInstalled checks node_modules/<name>/package.json', () => {
+    expect(isInstalled('esbuild')).toBeTruthy();
+    expect(isInstalled('surely-not-an-installed-package-xyz')).toBeFalsy();
+  });
+});

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

@@ -8,7 +8,7 @@ export function capitalized(input) {
   const formatted = input.replace(
     /\w*/g,
     function(txt) {
-      return txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase();
+      return txt.charAt(0).toUpperCase() + txt.slice(1).toLowerCase();
     }) 
   return formatted.replace(/,/g, '');
 }

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

@@ -4,6 +4,7 @@ export * from './get-files-recursive.js';
 export * from './run-command.js';
 export * from './run-script.js';
 export * from './prompt-boolean.js';
-export * from './languages.js';
 export * from './error-exit.js';
 export * from './build-lock.js';
+export * from './resolve-port.js';
+export * from './ensure-deps.js';

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

@@ -16,7 +16,7 @@ export const chalk = {
 };
 
 export const print = {
-  head: (s) => console.info(`${chalk.purple(s)}`),  
+  head: (s) => console.info(`${chalk.purple(s)}`),
   boldHead : (s) => console.info(`${chalk.boldPurple(s)}`),
   section: (s) => console.info(`${chalk.yellow(s)}`),
   boldSection: (s) => console.info(`${chalk.boldYellow(s)}`),
@@ -32,6 +32,6 @@ export const print = {
   boldError: (s) => console.error(`${chalk.boldRed(s)}`),
   grayError: (s) => console.error(`${chalk.boldGray(s)}`),
   warn: (s) => console.warn(`${chalk.yellow(s)}`),
-  boldWarn: (s) => console.warn(`${chalk.yellow(s)}`),
+  boldWarn: (s) => console.warn(`${chalk.boldYellow(s)}`),
   debug: (s) => console.debug(`${chalk.gray(s)}`),
 }

package/templates/base/tools/utils/resolve-port.js.hbs

@@ -0,0 +1,30 @@
+export const DEFAULT_PORT = 9090;
+
+// Precedence: --port flag > npm_config_port > PORT env > DEFAULT_PORT.
+// npm_config_port covers older npm versions turning `npm run dev --port=3000`
+// (no `--`) into config instead of argv; npm >= 11 rejects that with EUNKNOWNCONFIG.
+export function resolvePort(argv = process.argv.slice(2), env = process.env) {
+  const raw = readPortFlag(argv) ?? env.npm_config_port ?? env.PORT;
+  if (raw === undefined || raw === '') return DEFAULT_PORT;
+
+  const port = Number(raw);
+  if (!/^\d+$/.test(String(raw)) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port "${raw}" — expected an integer between 1 and 65535.`);
+  }
+  return port;
+}
+
+function readPortFlag(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--port=')) return arg.slice('--port='.length);
+    if (arg === '--port') {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        throw new Error('Missing value for --port (e.g. --port 3000).');
+      }
+      return next;
+    }
+  }
+  return undefined;
+}

package/templates/base/tools/utils/resolve-port.test.js.hbs

@@ -0,0 +1,47 @@
+import { resolvePort, DEFAULT_PORT } from './resolve-port.js';
+
+describe('resolvePort', () => {
+  it('defaults to 9090 with no flag or env', () => {
+    expect(resolvePort([], {})).toBe(DEFAULT_PORT);
+    expect(DEFAULT_PORT).toBe(9090);
+  });
+
+  it('reads --port <n>', () => {
+    expect(resolvePort(['--port', '3000'], {})).toBe(3000);
+  });
+
+  it('reads --port=<n>', () => {
+    expect(resolvePort(['--silent', '--port=3001'], {})).toBe(3001);
+  });
+
+  it('reads npm_config_port (npm rewrites --port into config)', () => {
+    expect(resolvePort([], { npm_config_port: '3002' })).toBe(3002);
+  });
+
+  it('reads PORT', () => {
+    expect(resolvePort([], { PORT: '3003' })).toBe(3003);
+  });
+
+  it('prefers --port over npm_config_port over PORT', () => {
+    expect(resolvePort(['--port', '1111'], { npm_config_port: '2222', PORT: '3333' })).toBe(1111);
+    expect(resolvePort([], { npm_config_port: '2222', PORT: '3333' })).toBe(2222);
+  });
+
+  it('ignores an empty PORT', () => {
+    expect(resolvePort([], { PORT: '' })).toBe(DEFAULT_PORT);
+  });
+
+  it('throws on a non-numeric port', () => {
+    expect(() => resolvePort(['--port', 'abc'], {})).toThrow('Invalid port "abc"');
+  });
+
+  it('throws on out-of-range ports', () => {
+    expect(() => resolvePort(['--port=0'], {})).toThrow('Invalid port "0"');
+    expect(() => resolvePort([], { PORT: '70000' })).toThrow('Invalid port "70000"');
+  });
+
+  it('throws when --port has no value', () => {
+    expect(() => resolvePort(['--port'], {})).toThrow('Missing value for --port');
+    expect(() => resolvePort(['--port', '--silent'], {})).toThrow('Missing value for --port');
+  });
+});

package/templates/base/tools/utils/run-command.js.hbs

@@ -1,8 +1,19 @@
 import { spawn } from 'child_process';
 
+const isWindows = process.platform === 'win32';
+
+// Windows needs a shell to launch .cmd shims (npm, tsc, ...); a single pre-quoted command
+// string avoids Node's deprecated args-array-with-shell form. Elsewhere no shell is
+// involved, so arguments containing spaces or shell characters are passed through as-is.
+function quoteForCmd(arg) {
+  return /[\s"&|<>^]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
+}
+
 export function runCommand(command, args = [], options = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn([command, ...args].join(' '), { stdio: 'inherit', shell: true, ...options });
+    const child = isWindows
+      ? spawn([command, ...args].map(quoteForCmd).join(' '), { stdio: 'inherit', shell: true, ...options })
+      : spawn(command, args, { stdio: 'inherit', ...options });
 
     child.on('error', (err) => reject(err));
 
@@ -12,3 +23,21 @@ export function runCommand(command, args = [], options = {}) {
     });
   });
 }
+
+// Like runCommand(), but collects the child's stdout and stderr (interleaved, in arrival order)
+// instead of printing them, and resolves with its exit code rather than rejecting: for a caller
+// that rewrites the output, e.g. compile-ts mapping tsc errors back to source files.
+export function captureCommand(command, args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const stdio = ['inherit', 'pipe', 'pipe'];
+    const child = isWindows
+      ? spawn([command, ...args].map(quoteForCmd).join(' '), { stdio, shell: true, ...options })
+      : spawn(command, args, { stdio, ...options });
+
+    let output = '';
+    child.stdout.on('data', (chunk) => { output += chunk; });
+    child.stderr.on('data', (chunk) => { output += chunk; });
+    child.on('error', (err) => reject(err));
+    child.on('close', (code) => resolve({ code, output }));
+  });
+}

package/templates/base/tools/utils/run-command.test.js.hbs

@@ -1,4 +1,4 @@
-import { runCommand } from './run-command.js';
+import { runCommand, captureCommand } from './run-command.js';
 
 describe('runCommand', () => {
   it('resolves when the child process exits with code 0', async () => {
@@ -16,4 +16,15 @@ describe('runCommand', () => {
     expect(error).toBeDefined();
     expect(error.message).toContain('7');
   });
+
+  it('passes arguments containing spaces through unsplit', async () => {
+    await runCommand('node', ['-e', 'if (process.argv[1] !== "a b") process.exitCode = 1', 'a b']);
+  });
+
+  it('captureCommand resolves with the exit code and the collected stdout and stderr', async () => {
+    const { code, output } = await captureCommand('node', ['-e', 'console.log("out"); console.error("err"); process.exitCode = 2']);
+    expect(code).toBe(2);
+    expect(output).toContain('out');
+    expect(output).toContain('err');
+  });
 });

package/templates/base/tools/utils/run-script.js.hbs

@@ -1,7 +1,7 @@
 import { resolve } from 'path';
 import { spawnSync } from 'child_process';
 import process from 'process';
-import { print } from './index.js';
+import { print } from './print.js';
 
 export function runScript(path, message) {
   if (!message) print.boldSection(`Running ${path}...`);
@@ -9,7 +9,7 @@ export function runScript(path, message) {
 
   const args = [resolve(path), '--silent'];
 
-  const result = spawnSync('node', args,
+  const result = spawnSync(process.execPath, args,
     { 
       stdio: 'inherit',
       env: { ...process.env }, 

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

@@ -23,11 +23,14 @@ RUN {{ciCommand}} || pnpm approve-builds --all
 {{else}}
 RUN {{ciCommand}}
 {{/if}}
+{{#unless (eq lang "js")}}
 COPY tsconfig.json .
+{{/unless}}
 COPY ./src ./src
 COPY ./public ./public
 COPY ./nutin.config.js .
 COPY ./config ./config
+__MARKDOWN_SOURCES_PLACEHOLDER__
 COPY ./tools/builder ./tools/builder
 COPY ./tools/docker ./tools/docker
 COPY ./tools/utils ./tools/utils

package/templates/features/docker/tools/docker/nginx.conf.template

@@ -10,7 +10,7 @@ map $uri $content_type_options {
 }
 
 map $uri $xss_protection {
-    default "1; mode=block";
+    default "0";
 }
 
 map $uri $referrer_policy {
@@ -56,8 +56,9 @@ server {
     # Hide nginx version
     server_tokens off;
 
-    # With i18n enabled, redirects bare "/" to the default language so the served URL
-    # always matches each page's canonical/og:url (filled in by validate-docker).
+    # With i18n enabled, redirects "/" and unprefixed paths ("/docs") to the default
+    # language, so every served URL matches a page's canonical/og:url instead of
+    # returning a duplicate SPA shell (filled in by validate-docker).
     __ROOT_REDIRECT_PLACEHOLDER__
 
     # SPA routing: serve index.html for unknown paths
@@ -109,7 +110,8 @@ server {
     # ---------------------------
     # HEALTH ENDPOINT
     # ---------------------------
-    location /health {
+    # Exact match: it must win over the i18n unprefixed-path redirect (a regex location).
+    location = /health {
         access_log off;
         add_header Content-Type text/plain always;
         add_header Cache-Control "no-store" always;

package/templates/features/docker/tools/docker/scripts/docker-ports.js.hbs

@@ -31,7 +31,7 @@ export function validateDockerPorts(rawPorts) {
     }
 
     if (port > MAX_PORT) {
-      throw new Error(`nutin.config.js: "dockerPorts[${i}]" (${port}) is in the OS ephemeral port range (49152-65535) — use a registered port between ${MIN_PORT} and ${MAX_PORT}.`);
+      throw new Error(`nutin.config.js: "dockerPorts[${i}]": use a registered port between ${MIN_PORT} and ${MAX_PORT}.`);
     }
 
     if (port < MIN_PORT || port > MAX_PORT) {

package/templates/features/docker/tools/docker/scripts/docker-ports.test.js.hbs

@@ -29,8 +29,8 @@ describe('validateDockerPorts', () => {
   });
 
   it('throws for ephemeral ports at or above 49152', () => {
-    expect(() => validateDockerPorts([49152])).toThrow('ephemeral port range');
-    expect(() => validateDockerPorts([60000])).toThrow('ephemeral port range');
+    expect(() => validateDockerPorts([49152])).toThrow('use a registered port');
+    expect(() => validateDockerPorts([60000])).toThrow('use a registered port');
   });
 
   it('throws for duplicate ports', () => {

package/templates/features/docker/tools/docker/scripts/locale-redirects.js.hbs

@@ -0,0 +1,28 @@
+// Language codes end up in an nginx regex and redirect target: letters, digits and "-" only (e.g. "pt-BR").
+const LANGUAGE_CODE = /^[A-Za-z0-9-]+$/;
+
+// Only i18n builds serve every page under a language prefix — without it, "/" and every
+// other path are real pages, and nothing is redirected.
+export function localeRedirects({ i18n, languages, defaultLanguage }) {
+  if (!i18n) return '';
+
+  [defaultLanguage, ...languages].forEach((lang) => {
+    if (typeof lang !== 'string' || !LANGUAGE_CODE.test(lang)) {
+      throw new Error(`config/languages.json: invalid language code ${JSON.stringify(lang)} — use letters, digits and "-" only (e.g. "en", "pt-BR").`);
+    }
+  });
+
+  // Unprefixed app paths (old or external links like "/docs") get a 301 to the default
+  // language instead of a 200 SPA shell that duplicates the real page. Paths with a "."
+  // (robots.txt, sitemap.xml, assets) are left to the other locations. $request_uri is
+  // the raw request (query included): the decoded $uri could inject headers via %0D%0A.
+  return [
+    `location = / {`,
+    `        return 301 /${defaultLanguage}/$is_args$args;`,
+    `    }`,
+    ``,
+    `    location ~ ^/(?!(?:${languages.join('|')})(?:/|$))[^.]*$ {`,
+    `        return 301 /${defaultLanguage}$request_uri;`,
+    `    }`,
+  ].join('\n');
+}

package/templates/features/docker/tools/docker/scripts/locale-redirects.test.js.hbs

@@ -0,0 +1,34 @@
+import { localeRedirects } from './locale-redirects.js';
+
+describe('localeRedirects', () => {
+  it('redirects nothing without i18n', () => {
+    expect(localeRedirects({ i18n: false, languages: ['en'], defaultLanguage: 'en' })).toBe('');
+  });
+
+  it('redirects "/" to the default language', () => {
+    const conf = localeRedirects({ i18n: true, languages: ['en', 'fr'], defaultLanguage: 'fr' });
+    expect(conf).toContain('location = / {\n        return 301 /fr/$is_args$args;\n    }');
+  });
+
+  it('redirects unprefixed, extensionless paths with the raw request URI', () => {
+    const conf = localeRedirects({ i18n: true, languages: ['en', 'fr'], defaultLanguage: 'en' });
+    expect(conf).toContain('location ~ ^/(?!(?:en|fr)(?:/|$))[^.]*$ {\n        return 301 /en$request_uri;\n    }');
+  });
+
+  it('only matches unprefixed, extensionless paths', () => {
+    const conf = localeRedirects({ i18n: true, languages: ['en', 'pt-BR'], defaultLanguage: 'en' });
+    const pattern = new RegExp(conf.match(/location ~ (\S+) \{/)[1]);
+
+    ['/docs', '/docs/', '/docs/api/x', '/english', '/enx/docs', '/pt-BRx'].forEach((path) => {
+      expect(pattern.test(path)).toBe(true);
+    });
+    ['/en', '/en/', '/en/docs/', '/pt-BR/docs', '/robots.txt', '/main.1a2b.css', '/assets/og.jpg'].forEach((path) => {
+      expect(pattern.test(path)).toBe(false);
+    });
+  });
+
+  it('throws on a language code that could break the nginx config', () => {
+    expect(() => localeRedirects({ i18n: true, languages: ['en', 'f r'], defaultLanguage: 'en' })).toThrow('invalid language code');
+    expect(() => localeRedirects({ i18n: true, languages: ['en'], defaultLanguage: 'en|.*' })).toThrow('invalid language code');
+  });
+});

package/templates/features/docker/tools/docker/scripts/markdown-sources-copy.js.hbs

@@ -0,0 +1,25 @@
+import path from 'path';
+
+// Markdown folders live outside src/ but build:prod compiles them, so the Docker
+// builder stage needs them too. Returns one COPY line per folder ('' without markdown).
+export function markdownSourcesCopy(sourceFolders, cwd = process.cwd()) {
+  const folders = (sourceFolders ?? [])
+    .map((entry) => (typeof entry === 'string' ? entry : entry?.folder))
+    .filter(Boolean);
+
+  const relativePaths = folders.map((folder) => {
+    const relative = path.relative(cwd, path.resolve(cwd, folder));
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error(`Markdown folder "${folder}" is outside the project, so it can't be copied into the Docker image — move it inside the project.`);
+    }
+    return relative.split(path.sep).join('/');
+  });
+
+  // JSON form keeps folder names with spaces intact.
+  return [...new Set(relativePaths)]
+    .map((relative) => {
+      const target = `./${relative}`;
+      return `COPY ${JSON.stringify([target, target])}`;
+    })
+    .join('\n');
+}

package/templates/features/docker/tools/docker/scripts/markdown-sources-copy.test.js.hbs

@@ -0,0 +1,34 @@
+import path from 'path';
+import { markdownSourcesCopy } from './markdown-sources-copy.js';
+
+describe('markdownSourcesCopy', () => {
+  const cwd = path.resolve('/project');
+
+  it('returns an empty string without markdown folders', () => {
+    expect(markdownSourcesCopy(undefined, cwd)).toBe('');
+    expect(markdownSourcesCopy([], cwd)).toBe('');
+  });
+
+  it('returns one COPY line per folder, for string and object entries', () => {
+    expect(markdownSourcesCopy(['markdown-content', { folder: 'docs/guides' }], cwd)).toBe(
+      'COPY ["./markdown-content","./markdown-content"]\nCOPY ["./docs/guides","./docs/guides"]'
+    );
+  });
+
+  it('keeps folder names with spaces in a single path', () => {
+    expect(markdownSourcesCopy(['my docs'], cwd)).toBe('COPY ["./my docs","./my docs"]');
+  });
+
+  it('copies a folder once when it is listed with different spellings', () => {
+    expect(markdownSourcesCopy(['docs', './docs/', { folder: 'docs' }], cwd)).toBe('COPY ["./docs","./docs"]');
+  });
+
+  it('skips entries without a folder', () => {
+    expect(markdownSourcesCopy([null, {}, 'docs'], cwd)).toBe('COPY ["./docs","./docs"]');
+  });
+
+  it('throws for a folder outside the project', () => {
+    expect(() => markdownSourcesCopy(['../shared-docs'], cwd)).toThrow('"../shared-docs" is outside the project');
+    expect(() => markdownSourcesCopy([path.resolve('/elsewhere/docs')], cwd)).toThrow('is outside the project');
+  });
+});

package/templates/features/docker/tools/docker/scripts/render-docker-template.js.hbs

@@ -14,7 +14,9 @@ export async function renderFromTemplate(dockerDir, templateName, outputName, re
 
   for (const [placeholder, value] of replacements) {
     if (!content.includes(placeholder)) {
-      throw new Error(`tools/docker/${templateName} is missing the "${placeholder}" token — validate-docker has nothing to substitute. Restore the token or re-run "nutin-add docker".`);
+      // Nothing to insert: a template from before this token was added still renders.
+      if (value === '') continue;
+      throw new Error(`tools/docker/${templateName} is missing the "${placeholder}" token — validate-docker has nothing to substitute. Add the token back — "nutin-update" reports the current template's changes.`);
     }
     content = content.replace(placeholder, value);
   }

package/templates/features/docker/tools/docker/scripts/render-docker-template.test.js.hbs

@@ -46,6 +46,18 @@ describe('renderFromTemplate', () => {
     ).toThrow('missing.template');
   });
 
+  it('skips a missing placeholder token when its value is empty', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'Dockerfile.template'), 'ARG PORT="__PORTS_PLACEHOLDER__"\n');
+
+    await renderFromTemplate(tmpDir, 'Dockerfile.template', 'Dockerfile', [
+      ['__PORTS_PLACEHOLDER__', '8080'],
+      ['__MARKDOWN_SOURCES_PLACEHOLDER__', ''],
+    ]);
+
+    const output = fs.readFileSync(path.join(tmpDir, 'Dockerfile'), 'utf-8');
+    expect(output).toBe('ARG PORT="8080"\n');
+  });
+
   it('throws when a placeholder token is missing from the template, without writing the output', async () => {
     fs.writeFileSync(path.join(tmpDir, 'nginx.conf.template'), 'listen 9090;\n');