@nocobase/cli 2.2.0-alpha.1 → 2.2.0-alpha.3

package/bin/early-locale.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function normalizeEarlyCliLocale(value) {
+  const normalized = String(value ?? '')
+    .trim()
+    .replace(/\..*$/, '')
+    .replace(/_/g, '-')
+    .toLowerCase();
+
+  if (normalized === 'zh' || normalized.startsWith('zh-')) {
+    return 'zh-CN';
+  }
+
+  if (normalized === 'en' || normalized.startsWith('en-')) {
+    return 'en-US';
+  }
+
+  return undefined;
+}
+
+function readConfiguredEarlyCliLocale() {
+  try {
+    const cliHomeRoot = String(process.env.NB_CLI_ROOT ?? '').trim() || os.homedir();
+    const configPath = path.join(cliHomeRoot, '.nocobase', 'config.json');
+    const content = fs.readFileSync(configPath, 'utf8');
+    const parsed = JSON.parse(content);
+    return normalizeEarlyCliLocale(parsed?.settings?.locale);
+  } catch {
+    return undefined;
+  }
+}
+
+export function detectEarlyCliLocale() {
+  const candidates = [
+    process.env.NB_LOCALE,
+    readConfiguredEarlyCliLocale(),
+    process.env.LC_ALL,
+    process.env.LC_MESSAGES,
+    process.env.LANG,
+    Intl.DateTimeFormat().resolvedOptions().locale,
+  ];
+
+  for (const candidate of candidates) {
+    const locale = normalizeEarlyCliLocale(candidate);
+    if (locale) {
+      return locale;
+    }
+  }
+
+  return 'en-US';
+}
+
+function getEarlyLocalePathValue(input, key) {
+  let current = input;
+  for (const part of key.split('.')) {
+    if (!current || typeof current !== 'object' || !Object.prototype.hasOwnProperty.call(current, part)) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return typeof current === 'string' ? current : undefined;
+}
+
+function readEarlyLocaleMessages(locale) {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(moduleDir, '..');
+  const localePaths = [
+    path.join(packageRoot, 'src', 'locale', `${locale}.json`),
+    path.join(packageRoot, 'dist', 'locale', `${locale}.json`),
+  ];
+
+  for (const localePath of localePaths) {
+    try {
+      return JSON.parse(fs.readFileSync(localePath, 'utf8'));
+    } catch {
+      // Try the next runtime layout.
+    }
+  }
+
+  return undefined;
+}
+
+export function translateEarlyCli(key, fallback, locale = detectEarlyCliLocale()) {
+  const messages = readEarlyLocaleMessages(locale);
+  return getEarlyLocalePathValue(messages, key) ?? fallback;
+}

package/bin/node-version.js

@@ -0,0 +1,35 @@
+const MINIMUM_NODE_MAJOR_VERSION = 22;
+
+export function getNodeMajorVersion(version = process.versions.node) {
+  const match = String(version ?? '')
+    .trim()
+    .match(/^v?(\d+)/);
+
+  if (!match) {
+    return Number.NaN;
+  }
+
+  return Number.parseInt(match[1], 10);
+}
+
+export function isSupportedNodeVersion(
+  version = process.versions.node,
+  minimumMajorVersion = MINIMUM_NODE_MAJOR_VERSION,
+) {
+  const majorVersion = getNodeMajorVersion(version);
+  return Number.isInteger(majorVersion) && majorVersion >= minimumMajorVersion;
+}
+
+export function formatUnsupportedNodeVersionMessage(
+  version = process.version,
+  minimumMajorVersion = MINIMUM_NODE_MAJOR_VERSION,
+) {
+  const currentVersion = String(version ?? '').trim() || 'unknown';
+
+  return [
+    `[nocobase cli]: Node.js ${minimumMajorVersion} or later is required to run nb.`,
+    `[nocobase cli]: Current version: ${currentVersion}. Please install Node.js ${minimumMajorVersion} or later and try again.`,
+  ].join('\n');
+}
+
+export { MINIMUM_NODE_MAJOR_VERSION };

package/bin/run.js

@@ -6,7 +6,9 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import pc from 'picocolors';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { formatUnsupportedNodeVersionMessage, isSupportedNodeVersion } from './node-version.js';
 import { normalizeNodeOptions, normalizeSessionEnv } from './session-env.js';
+import { ensureWindowsAdministrator } from './windows-admin.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const requireFromCli = createRequire(import.meta.url);
@@ -18,9 +20,16 @@ if (process.env.NB_CLI_USE_DIST === '1') {
   isDev = false;
 }
 
+if (!isSupportedNodeVersion()) {
+  console.error(pc.red(formatUnsupportedNodeVersionMessage(process.version)));
+  process.exit(1);
+}
+
 normalizeSessionEnv();
 normalizeNodeOptions();
 
+ensureWindowsAdministrator();
+
 /**
  * In the monorepo, plain `node` cannot load `.ts`. Re-exec once with `--import <tsx>`
  * (same effect as a dedicated dev entry with `#!/usr/bin/env -S node --import tsx`).

package/bin/windows-admin.js

@@ -0,0 +1,60 @@
+import { spawnSync } from 'node:child_process';
+import pc from 'picocolors';
+import { detectEarlyCliLocale, translateEarlyCli } from './early-locale.js';
+
+const windowsAdministratorCheckScript = [
+  '$identity = [Security.Principal.WindowsIdentity]::GetCurrent();',
+  '$principal = New-Object Security.Principal.WindowsPrincipal($identity);',
+  'if ($principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { exit 0 }',
+  'exit 1',
+].join(' ');
+
+export function formatWindowsAdministratorRequiredMessage() {
+  const locale = detectEarlyCliLocale();
+  const message = translateEarlyCli(
+    'entry.windowsAdministratorRequired.message',
+    'NocoBase CLI must be run as Administrator on Windows.',
+    locale,
+  );
+  const hint = translateEarlyCli(
+    'entry.windowsAdministratorRequired.hint',
+    'Open your terminal as Administrator, then run the command again.',
+    locale,
+  );
+
+  return [message, hint].join('\n');
+}
+
+function isWindowsAdministrator() {
+  for (const command of ['pwsh.exe', 'powershell.exe']) {
+    const result = spawnSync(
+      command,
+      ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', windowsAdministratorCheckScript],
+      {
+        stdio: 'ignore',
+        windowsHide: true,
+      },
+    );
+
+    if (result.error?.code === 'ENOENT') {
+      continue;
+    }
+
+    return result.status === 0;
+  }
+
+  return false;
+}
+
+export function ensureWindowsAdministrator() {
+  if (process.platform !== 'win32' || process.env.NB_CLI_WINDOWS_ADMIN_CHECKED === '1') {
+    return;
+  }
+
+  if (!isWindowsAdministrator()) {
+    console.error(pc.red(formatWindowsAdministratorRequiredMessage()));
+    process.exit(1);
+  }
+
+  process.env.NB_CLI_WINDOWS_ADMIN_CHECKED = '1';
+}

package/dist/commands/app/destroy.js

@@ -143,6 +143,7 @@ export default class AppDestroy extends Command {
         }
         announceTargetEnv(runtime.envName);
         try {
+            const retryCommand = `nb env remove ${runtime.envName} --purge --force`;
             if (runtime.kind === 'docker') {
                 startTask(`Removing Docker app container for "${runtime.envName}"...`);
                 const state = await removeDockerContainerIfExists(runtime.containerName, {
@@ -192,7 +193,7 @@ export default class AppDestroy extends Command {
                     const localAppPath = resolveManagedLocalAppPath(runtime);
                     if (localAppPath && removesManagedLocalAppFiles) {
                         startTask(`Removing managed local app files for "${runtime.envName}"...`);
-                        await removePathIfExists(localAppPath, `managed app files for "${runtime.envName}"`);
+                        await removePathIfExists(localAppPath, `managed app files for "${runtime.envName}"`, { retryCommand });
                         succeedTask(`Managed local app files removed for "${runtime.envName}".`);
                     }
                     else {
@@ -206,13 +207,13 @@ export default class AppDestroy extends Command {
                 ];
                 startTask(`Removing proxy entry files for "${runtime.envName}"...`);
                 for (const proxyEntryDir of proxyEntryDirs) {
-                    await removePathIfExists(proxyEntryDir, `proxy entry files for "${runtime.envName}"`);
+                    await removePathIfExists(proxyEntryDir, `proxy entry files for "${runtime.envName}"`, { retryCommand });
                 }
                 succeedTask(`Proxy entry files removed for "${runtime.envName}".`);
                 const configuredStoragePath = resolveConfiguredStoragePath(runtime.env.config);
                 if (configuredStoragePath) {
                     startTask(`Removing storage data for "${runtime.envName}"...`);
-                    await removePathIfExists(configuredStoragePath, `storage data for "${runtime.envName}"`);
+                    await removePathIfExists(configuredStoragePath, `storage data for "${runtime.envName}"`, { retryCommand });
                     succeedTask(`Storage data removed for "${runtime.envName}".`);
                 }
                 else {

package/dist/commands/app/restart.js

@@ -14,6 +14,7 @@ import { recreateSavedDockerApp } from '../../lib/app-managed-resources.js';
 import { resolveAppUrlFromApiBaseUrl } from '../env/shared.js';
 import { run } from '../../lib/run-npm.js';
 import { announceTargetEnv, failTask, startTask, succeedTask } from '../../lib/ui.js';
+import { buildHookContext, resolveHookScriptPath, runHookScriptHook } from '../../lib/hook-script.js';
 function argvHasToken(argv, tokens) {
     return tokens.some((token) => argv.includes(token));
 }
@@ -62,6 +63,39 @@ function resolveDisplayAppUrl(apiBaseUrl, port, appPublicPath) {
     }
     return formatAppUrl(port, appPublicPath);
 }
+async function runDockerAfterAppStartHookIfNeeded(runtime) {
+    const hookScript = runtime.env.config?.hookScript;
+    if (!hookScript) {
+        return;
+    }
+    const hookScriptPath = resolveHookScriptPath({
+        appPath: runtime.env.appPath,
+        hookScript,
+    });
+    if (!hookScriptPath) {
+        return;
+    }
+    const context = buildHookContext({
+        phase: 'app-start',
+        command: 'app:restart',
+        envName: runtime.envName,
+        source: runtime.source,
+        version: runtime.env.config?.downloadVersion,
+        appPath: runtime.env.appPath,
+        sourcePath: runtime.env.sourcePath,
+        storagePath: runtime.env.storagePath,
+        hookScript: String(hookScript).trim(),
+        envConfig: runtime.env.config,
+    });
+    if (!context) {
+        return;
+    }
+    await runHookScriptHook({
+        hookScriptPath,
+        hookName: 'afterAppStart',
+        context,
+    });
+}
 export default class AppRestart extends Command {
     static hidden = false;
     static description = 'Restart NocoBase for the selected env. When applicable, the CLI synchronizes licensed commercial plugins first, then restarts the local app or recreates the saved Docker container.';
@@ -199,6 +233,7 @@ export default class AppRestart extends Command {
                 logHint: `You can inspect startup logs with \`nb app logs --env ${runtime.envName}\`.`,
                 ...(flags.verbose ? { verbose: true } : {}),
             });
+            await runDockerAfterAppStartHookIfNeeded(runtime);
             succeedTask(`NocoBase is running for "${runtime.envName}"${appUrl ? ` at ${appUrl}` : ''}.`);
             return;
         }
@@ -222,6 +257,9 @@ export default class AppRestart extends Command {
         if (daemonFlagWasProvided) {
             startArgv.push(flags.daemon === false ? '--no-daemon' : '--daemon');
         }
+        if (runtime.env.config?.hookScript) {
+            startArgv.push('--hook-command', 'app:restart');
+        }
         await runWithSuppressedTargetEnvLog(async () => {
             await runCommand('app:start', startArgv);
         });

package/dist/commands/app/shared.js

@@ -25,10 +25,54 @@ function assertSafeRemovalPath(target, label) {
         throw new Error(`Refusing to remove ${label} at "${resolved}" because it is too broad.`);
     }
 }
-export async function removePathIfExists(target, label) {
+function getErrorCode(error) {
+    if (!(error instanceof Error)) {
+        return undefined;
+    }
+    const { code } = error;
+    return typeof code === 'string' ? code : undefined;
+}
+function isPermissionDeniedError(error) {
+    const code = getErrorCode(error);
+    return code === 'EACCES' || code === 'EPERM';
+}
+function formatOriginalError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = getErrorCode(error);
+    return code && !message.includes(code) ? `${code}: ${message}` : message;
+}
+function quoteShellValue(value) {
+    return `"${value.replace(/(["\\$`])/g, '\\$1')}"`;
+}
+function formatPermissionDeniedRemovalError(target, label, error, options) {
+    const retryLines = os.platform() === 'win32' ? [] : [`  sudo chown -R "$(id -u):$(id -g)" ${quoteShellValue(target)}`];
+    if (options.retryCommand) {
+        retryLines.push(`  ${options.retryCommand}`);
+    }
+    return [
+        `Failed to remove ${label} at "${target}".`,
+        'The current user cannot delete one or more files under this path. Files may have been created by a Docker container running as root.',
+        '',
+        retryLines.length > 0
+            ? 'Fix ownership or permissions, then retry:'
+            : 'Fix ownership or permissions, then retry the command.',
+        ...retryLines,
+        '',
+        `Original error: ${formatOriginalError(error)}`,
+    ].join('\n');
+}
+export async function removePathIfExists(target, label, options = {}) {
     const resolved = path.resolve(target);
     assertSafeRemovalPath(resolved, label);
-    await fsp.rm(resolved, { recursive: true, force: true });
+    try {
+        await fsp.rm(resolved, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (isPermissionDeniedError(error)) {
+            throw new Error(formatPermissionDeniedRemovalError(resolved, label, error, options));
+        }
+        throw error;
+    }
 }
 function isMissingDockerContainerError(error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -116,7 +160,9 @@ export function managedDockerNetworkName(runtime) {
     return runtime.dockerNetworkName?.trim() || runtime.workspaceName?.trim() || undefined;
 }
 export function resolveManagedLocalAppPath(runtime) {
-    return resolveConfiguredAppPath(runtime.env.config) || runtime.projectRoot || resolveConfiguredPath(runtime.env.config.appRootPath);
+    return (resolveConfiguredAppPath(runtime.env.config) ||
+        runtime.projectRoot ||
+        resolveConfiguredPath(runtime.env.config.appRootPath));
 }
 export function shouldRemoveManagedLocalAppFiles(runtime) {
     return runtime.source === 'npm' || runtime.source === 'git' || runtime.source === 'local';

package/dist/commands/app/start.js

@@ -18,6 +18,7 @@ import { resolveAppUrlFromApiBaseUrl } from '../env/shared.js';
 import { readManagedRuntimeEnvValues } from '../../lib/managed-env-file.js';
 import { run } from '../../lib/run-npm.js';
 import { announceTargetEnv, failTask, printInfo, printWarning, startTask, succeedTask } from '../../lib/ui.js';
+import { buildHookContext, resolveHookScriptPath, runHookScriptHook, } from '../../lib/hook-script.js';
 function shouldPrintStartSuccess() {
     return process.env.NB_SKIP_APP_START_SUCCESS_LOG !== '1';
 }
@@ -34,6 +35,57 @@ function buildLicenseSyncArgv(envName, options) {
     }
     return argv;
 }
+function resolveHookCommand(value) {
+    const text = String(value ?? '').trim();
+    if (text === 'app:restart' || text === 'app:upgrade') {
+        return text;
+    }
+    return 'app:start';
+}
+function resolveAppStartHookPhase(options) {
+    if (options.isPreparedEnv) {
+        return 'init';
+    }
+    if (options.command === 'app:upgrade') {
+        return 'upgrade';
+    }
+    return 'app-start';
+}
+async function runRuntimeHookIfNeeded(params) {
+    const hookScript = params.runtime.env.config?.hookScript;
+    if (!hookScript) {
+        return;
+    }
+    const hookScriptPath = resolveHookScriptPath({
+        appPath: params.runtime.env.appPath,
+        hookScript,
+    });
+    if (!hookScriptPath) {
+        return;
+    }
+    const context = buildHookContext({
+        phase: params.phase,
+        command: params.command,
+        envName: params.runtime.envName,
+        source: params.runtime.source,
+        version: params.runtime.env.config?.downloadVersion,
+        appPath: params.runtime.env.appPath,
+        sourcePath: params.runtime.env.sourcePath,
+        storagePath: params.runtime.env.storagePath,
+        hookScript: String(hookScript).trim(),
+        envConfig: params.hookName === 'afterAppStart' && params.phase === 'init'
+            ? { ...params.runtime.env.config, setupState: 'installed' }
+            : params.runtime.env.config,
+    });
+    if (!context) {
+        return;
+    }
+    await runHookScriptHook({
+        hookScriptPath,
+        hookName: params.hookName,
+        context,
+    });
+}
 async function runWithSuppressedTargetEnvLog(task) {
     const previousTargetEnv = process.env.NB_SKIP_TARGET_ENV_LOG;
     process.env.NB_SKIP_TARGET_ENV_LOG = '1';
@@ -171,6 +223,10 @@ export default class AppStart extends Command {
             description: 'Show raw startup output from the underlying local or Docker command',
             default: false,
         }),
+        'hook-command': Flags.string({
+            hidden: true,
+            options: ['app:start', 'app:restart', 'app:upgrade'],
+        }),
     };
     async run() {
         const { flags } = await this.parse(AppStart);
@@ -192,6 +248,12 @@ export default class AppStart extends Command {
         const runtime = await resolveManagedAppRuntime(requestedEnv);
         const preparedInitEnvVars = buildInitAppEnvVarsFromConfig(runtime?.env.config);
         const isPreparedEnv = isPreparedSetupState(runtime?.env.config?.setupState);
+        const hookCommand = resolveHookCommand(flags['hook-command']);
+        const hookPhase = resolveAppStartHookPhase({
+            isPreparedEnv,
+            command: hookCommand,
+        });
+        const shouldRunBeforeAppInstall = isPreparedEnv || hookCommand === 'app:upgrade';
         const runCommand = this.config.runCommand.bind(this.config);
         const commandStdio = flags.verbose ? 'inherit' : 'ignore';
         if (!runtime) {
@@ -249,6 +311,14 @@ export default class AppStart extends Command {
                     errorName: 'docker rm',
                     stdio: commandStdio,
                 }).catch(() => undefined);
+                if (shouldRunBeforeAppInstall) {
+                    await runRuntimeHookIfNeeded({
+                        hookName: 'beforeAppInstall',
+                        runtime,
+                        phase: hookPhase,
+                        command: hookCommand,
+                    });
+                }
                 await recreateSavedDockerApp(runtime, {
                     initEnvVars: isPreparedEnv ? preparedInitEnvVars : undefined,
                     verbose: flags.verbose,
@@ -270,6 +340,12 @@ export default class AppStart extends Command {
             if (isPreparedEnv) {
                 await finalizePreparedEnv(runtime.envName);
             }
+            await runRuntimeHookIfNeeded({
+                hookName: 'afterAppStart',
+                runtime,
+                phase: hookPhase,
+                command: hookCommand,
+            });
             if (shouldPrintStartSuccess()) {
                 succeedTask(`NocoBase is running for "${runtime.envName}"${appUrl ? ` at ${appUrl}` : ''}.`);
             }
@@ -285,6 +361,8 @@ export default class AppStart extends Command {
             const downloadableRuntime = runtime;
             await ensureSavedLocalSource(downloadableRuntime, runCommand, {
                 verbose: flags.verbose,
+                hookPhase: isPreparedEnv ? 'init' : 'restore',
+                hookCommand,
                 onStartTask: startTask,
                 onSucceedTask: succeedTask,
                 onFailTask: failTask,
@@ -381,6 +459,14 @@ export default class AppStart extends Command {
                     ...managedAppLifecycleEnvVars(),
                     ...(isPreparedEnv ? preparedInitEnvVars : {}),
                 };
+            if (shouldRunBeforeAppInstall) {
+                await runRuntimeHookIfNeeded({
+                    hookName: 'beforeAppInstall',
+                    runtime,
+                    phase: hookPhase,
+                    command: hookCommand,
+                });
+            }
             await runLocalNocoBaseCommand(runtime, npmArgs, {
                 env: startEnv,
                 stdio: commandStdio,
@@ -394,6 +480,12 @@ export default class AppStart extends Command {
                 if (isPreparedEnv) {
                     await finalizePreparedEnv(runtime.envName);
                 }
+                await runRuntimeHookIfNeeded({
+                    hookName: 'afterAppStart',
+                    runtime,
+                    phase: hookPhase,
+                    command: hookCommand,
+                });
                 if (shouldPrintStartSuccess()) {
                     succeedTask(`NocoBase is running for "${runtime.envName}"${appUrl ? ` at ${appUrl}` : ''}.`);
                 }

package/dist/commands/app/upgrade.js

@@ -12,6 +12,7 @@ import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime, } from '..
 import { ensureCrossEnvConfirmed, hasExplicitEnvSelection } from '../../lib/env-guard.js';
 import { DEFAULT_DOCKER_REGISTRY } from "../../lib/docker-image.js";
 import { confirm } from "../../lib/inquirer.js";
+import { resolveHookScriptPath } from '../../lib/hook-script.js';
 import { announceTargetEnv, isInteractiveTerminal, printInfo, printWarning, succeedTask } from '../../lib/ui.js';
 import { resolveAppUrlFromApiBaseUrl } from '../env/shared.js';
 function trimValue(value) {
@@ -345,6 +346,13 @@ export default class AppUpgrade extends Command {
         if (runtime.env.config.buildDts === true) {
             argv.push('--build-dts');
         }
+        const hookScriptPath = resolveHookScriptPath({
+            appPath: runtime.env.appPath,
+            hookScript: runtime.env.config.hookScript,
+        });
+        if (hookScriptPath) {
+            argv.push('--hook-script', hookScriptPath, '--hook-phase', 'upgrade', '--hook-command', 'app:upgrade', '--hook-env-name', runtime.envName, '--hook-app-path', runtime.env.appPath, '--hook-storage-path', runtime.env.storagePath);
+        }
         return argv;
     }
     static buildDockerDownloadArgv(runtime, downloadVersion, options) {
@@ -497,6 +505,9 @@ export default class AppUpgrade extends Command {
             await runWithSuppressedTargetEnvLog(async () => {
                 const startArgv = buildManagedActionArgv(runtime.envName, parsed, { quickstart: true });
                 startArgv.push('--no-sync-licensed-plugins');
+                if (runtime.env.config.hookScript) {
+                    startArgv.push('--hook-command', 'app:upgrade');
+                }
                 await runWithSuppressedStartSuccessLog(async () => {
                     await runCommand('app:start', startArgv);
                 });

package/dist/commands/examples/prompts-stages.js

@@ -109,8 +109,8 @@ export default class PromptsStages extends Command {
                 values: presetValues,
                 pageTitle: 'nb prompts-stages — Web UI',
                 documentHeading: 'nb prompts-stages — `stages` demo',
-                onServerStart: ({ host, port, url }) => {
-                    this.log(`Local Web UI (multi-stage) ready — ${url} (listening on ${host}:${port}). Submit the form in the browser to continue.`);
+                onServerStart: ({ listenHost, port, url }) => {
+                    this.log(`Local Web UI (multi-stage) ready — ${url} (listening on ${listenHost}:${port}). Submit the form in the browser to continue.`);
                 },
                 onOpenBrowserError: (url, err) => {
                     this.log(`Open this URL in a browser: ${url} (${err instanceof Error ? err.message : String(err)})`);

package/dist/commands/examples/prompts-test.js

@@ -139,8 +139,8 @@ export default class PromptsTest extends Command {
                 values: presetValues,
                 pageTitle: 'nb prompts-test — UI',
                 documentHeading: 'nb prompts-test',
-                onServerStart: ({ host, port, url }) => {
-                    this.log(`Local Web UI ready — ${url} (listening on ${host}:${port}). Submit the form in the browser to continue.`);
+                onServerStart: ({ listenHost, port, url }) => {
+                    this.log(`Local Web UI ready — ${url} (listening on ${listenHost}:${port}). Submit the form in the browser to continue.`);
                 },
                 onOpenBrowserError: (url, err) => {
                     this.log(`Open this URL in a browser: ${url} (${err instanceof Error ? err.message : String(err)})`);