@nutin/cli 2.1.0 → 3.0.0

package/templates/base/tools/testin-nutin/mocks/mock-i18n.test.js.hbs

@@ -1,57 +1,78 @@
 import { MockI18n } from './mock-i18n.js';
 
 describe('MockI18n', () => {
-  it('exposes the constructor defaults via currentLanguage', () => {
+  it('exposes the constructor defaults via the language getters', () => {
     const i18n = new MockI18n('fr', ['en', 'fr']);
+
     expect(i18n.currentLanguage).toBe('fr');
+    expect(i18n.defaultLanguage).toBe('fr');
+    expect(i18n.languages).toEqual(['en', 'fr']);
   });
 
-  it('translate/getBrowserLanguage run their built-in default implementation without needing .mockImplementation', () => {
+  it('translate() falls back to textContent, then to the key itself', () => {
     const i18n = new MockI18n();
 
-    // No translations set — translate() falls back to returning the key itself.
+    expect(i18n.translate('some.key', 'Fallback text')).toBe('Fallback text');
     expect(i18n.translate('some.key')).toBe('some.key');
-    expect(i18n.getBrowserLanguage()).toBe('en');
   });
 
-  it('loadTranslations/initTranslations run their default implementation and update currentLanguage', async () => {
-    const i18n = new MockI18n('en', ['en', 'fr']);
+  it('translate() resolves nested dot keys from setTranslations()', () => {
+    const i18n = new MockI18n();
+    i18n.setTranslations({ home: { title: 'Home' } });
 
+    expect(i18n.translate('home.title')).toBe('Home');
+  });
+
+  it('translate() falls back to the default-language translations off the default language', async () => {
+    const i18n = new MockI18n('en', ['en', 'fr']);
+    i18n.setDefaultTranslations({ greeting: 'Hello' });
     await i18n.loadTranslations('fr');
-    expect(i18n.currentLanguage).toBe('fr');
+
+    expect(i18n.translate('greeting')).toBe('Hello');
   });
 
-  it('translate is still trackable as a mock alongside its default implementation', () => {
+  it('getTranslationObject() returns the nested value, or null', () => {
     const i18n = new MockI18n();
-    i18n.translate('some.key');
+    i18n.setTranslations({ nav: { home: 'Home', about: 'About' } });
 
-    expect(i18n.translate).toHaveBeenCalledWith('some.key');
+    expect(i18n.getTranslationObject('nav')).toEqual({ home: 'Home', about: 'About' });
+    expect(i18n.getTranslationObject('missing')).toBe(null);
   });
 
-  it('translate can be given real interpolation behavior via .mockImplementation', () => {
-    const i18n = new MockI18n();
-    i18n.setTranslations({ greeting: 'Hello {name}' });
-    i18n.translate.mockImplementation((key, params) => {
-      const value = i18n._translations[key] || key;
-      if (!params) return value;
-      return Object.entries(params).reduce((acc, [k, v]) => acc.replace(`{${k}}`, v), value);
-    });
+  it('setCurrentLanguage() updates currentLanguage and notifies onLanguageChange() callbacks', async () => {
+    const i18n = new MockI18n('en', ['en', 'fr']);
+    let payload;
+    i18n.onLanguageChange((data) => { payload = data; });
 
-    expect(i18n.translate('greeting', { name: 'Ada' })).toBe('Hello Ada');
+    await i18n.setCurrentLanguage('fr');
+
+    expect(i18n.currentLanguage).toBe('fr');
+    expect(payload).toEqual({ lang: 'fr' });
+    expect(i18n.setCurrentLanguage).toHaveBeenCalledWith('fr');
+  });
+
+  it('onLanguageChange() returns a function that stops further notifications', async () => {
+    const i18n = new MockI18n('en', ['en', 'fr']);
+    let calls = 0;
+    const unsubscribe = i18n.onLanguageChange(() => { calls++; });
+    unsubscribe();
+
+    await i18n.setCurrentLanguage('fr');
+
+    expect(calls).toBe(0);
   });
 
-  it('setTranslations/setDefaultTranslations seed real, readable state', () => {
+  it('translate is still trackable as a mock alongside its default implementation', () => {
     const i18n = new MockI18n();
-    i18n.setTranslations({ a: '1' });
-    i18n.setDefaultTranslations({ b: '2' });
+    i18n.translate('some.key');
 
-    expect(i18n._translations).toEqual({ a: '1' });
-    expect(i18n._defaultTranslations).toEqual({ b: '2' });
+    expect(i18n.translate).toHaveBeenCalledWith('some.key');
   });
 
-  it('reset() restores the constructor default language and clears translations', () => {
-    const i18n = new MockI18n('en');
+  it('reset() restores the constructor default language and clears translations', async () => {
+    const i18n = new MockI18n('en', ['en', 'fr']);
     i18n.setTranslations({ a: '1' });
+    await i18n.setCurrentLanguage('fr');
 
     i18n.reset();
 

package/templates/base/tools/testin-nutin/mocks/mock-router.js.hbs

@@ -1,23 +1,31 @@
 import { createMockMethod } from './create-mock-method.js';
 
+// Mirrors Router's public API. Route params are seeded with setParams() and read back
+// through the real getCurrentParams()/getParam() shapes.
 export class MockRouter {
   constructor(routes = {}) {
     this.routes = routes;
-    this._currentView = null;
+    this._currentParams = {};
 
-    this.navigate = createMockMethod();
-    this.handlePopState = createMockMethod();
-    this.handleNotFound = createMockMethod();
-    this.handleGuards = createMockMethod();
-    this.initializeEventListeners = createMockMethod();
+    this.navigate = createMockMethod(async () => {});
+    this.reload = createMockMethod(async () => {});
+    this.getCurrentParams = createMockMethod(() => ({ ...this._currentParams }));
+    this.getParam = createMockMethod((key) => this._currentParams[key]);
+    this.removeEventListeners = createMockMethod();
+    this.onDestroy = createMockMethod();
+  }
+
+  setParams(params) {
+    this._currentParams = { ...params };
   }
 
   reset() {
     this.navigate.mockReset();
-    this.handlePopState.mockReset();
-    this.handleNotFound.mockReset();
-    this.handleGuards.mockReset();
-    this.initializeEventListeners.mockReset();
-    this._currentView = null;
+    this.reload.mockReset();
+    this.getCurrentParams.mockReset();
+    this.getParam.mockReset();
+    this.removeEventListeners.mockReset();
+    this.onDestroy.mockReset();
+    this._currentParams = {};
   }
 }

package/templates/base/tools/testin-nutin/mocks/mock-router.test.js.hbs

@@ -8,22 +8,39 @@ describe('MockRouter', () => {
     expect(router.routes).toBe(routes);
   });
 
-  it('navigate/handlePopState/handleNotFound/handleGuards/initializeEventListeners are independent bare mocks', () => {
+  it('navigate/reload are independent trackable mocks', async () => {
     const router = new MockRouter();
-    router.navigate('/about');
+    await router.navigate('/about');
 
     expect(router.navigate.calls).toEqual([['/about']]);
-    expect(router.handlePopState.calls).toEqual([]);
+    expect(router.reload.calls).toEqual([]);
   });
 
-  it('reset() clears every mock method and _currentView', () => {
+  it('getCurrentParams/getParam read the params seeded with setParams()', () => {
     const router = new MockRouter();
-    router.navigate('/about');
-    router._currentView = 'about-view';
+    router.setParams({ id: '42' });
+
+    expect(router.getCurrentParams()).toEqual({ id: '42' });
+    expect(router.getParam('id')).toBe('42');
+    expect(router.getParam('missing')).toBe(undefined);
+  });
+
+  it('getCurrentParams returns a copy', () => {
+    const router = new MockRouter();
+    router.setParams({ id: '42' });
+    router.getCurrentParams().id = 'changed';
+
+    expect(router.getParam('id')).toBe('42');
+  });
+
+  it('reset() clears every mock method and the seeded params', async () => {
+    const router = new MockRouter();
+    await router.navigate('/about');
+    router.setParams({ id: '42' });
 
     router.reset();
 
     expect(router.navigate.calls).toEqual([]);
-    expect(router._currentView).toBe(null);
+    expect(router.getCurrentParams()).toEqual({});
   });
 });

package/templates/base/tools/testin-nutin/runner.js.hbs

@@ -12,7 +12,9 @@ const verboseEnabled = args.includes('--verbose');
 const fileFilters = args.filter(arg => arg !== '--coverage' && arg !== '--verbose');
 
 // Tests import and run the compiled build output (dist/src/)
+{{#unless (eq lang "js")}}
 // and has no sourcemap back to the .ts sources
+{{/unless}}
 const origins = [];
 const coverageDirs = [];
 
@@ -41,10 +43,8 @@ if (fileFilters.length) {
 }
 
 async function loadTestFile(file) {
-  setupJsdom();
   setCurrentTestFile(file);
   await import(file);
-  teardownJsdom();
 }
 
 async function runCoverage(testResults) {
@@ -77,18 +77,27 @@ async function runTests() {
 
   if (coverageEnabled) await startCoverage();
 
+  // One DOM for importing every file (module-level code may use it); each suite
+  // then runs in a fresh one (see runQueuedTests).
+  let loadFailures = 0;
+  setupJsdom();
   for (const file of testFiles) {
     try {
       await loadTestFile(file);
     } catch (error) {
+      loadFailures++;
       print.boldError(`✗ ${file} failed to load:`);
       print.grayError(error.stack);
     }
   }
+  teardownJsdom();
 
   const testResults = await runQueuedTests();
 
-  if (testResults.failed > 0) process.exitCode = 1;
+  if (loadFailures > 0) {
+    print.boldError(`✗ ${loadFailures} test file(s) failed to load — see errors above.\n`);
+  }
+  if (testResults.failed > 0 || loadFailures > 0) process.exitCode = 1;
 
   if (coverageEnabled) await runCoverage(testResults);
 }

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

@@ -0,0 +1,97 @@
+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() {
+  let mtimeMs;
+  try {
+    ({ 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() {
+  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);
+  // '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,5 +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');
+  });
+});