@nocobase/cli 2.1.0-alpha.40 → 2.1.0-alpha.46

package/dist/lib/app-health.js

@@ -6,10 +6,12 @@
  * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
-import { printInfo, startTask, stopTask, updateTask } from './ui.js';
+import { startDockerLogFollower } from './docker-log-stream.js';
+import { printInfo } from './ui.js';
 const APP_HEALTH_CHECK_INTERVAL_MS = 2_000;
 const APP_HEALTH_CHECK_TIMEOUT_MS = 600_000;
 const APP_HEALTH_CHECK_REQUEST_TIMEOUT_MS = 5_000;
+const APP_HEALTH_CHECK_PROGRESS_LOG_INTERVAL_MS = 10_000;
 function trimValue(value) {
     return String(value ?? '').trim();
 }
@@ -92,35 +94,46 @@ export async function waitForAppReady(params) {
     }
     const healthCheckUrl = buildHealthCheckUrl(apiBaseUrl);
     const startedAt = Date.now();
+    const timeoutMs = params.timeoutMs ?? APP_HEALTH_CHECK_TIMEOUT_MS;
+    const intervalMs = params.intervalMs ?? APP_HEALTH_CHECK_INTERVAL_MS;
+    const progressLogIntervalMs = Math.max(1, params.progressLogIntervalMs ?? APP_HEALTH_CHECK_PROGRESS_LOG_INTERVAL_MS);
     let lastMessage = 'No response yet';
-    let spinnerActive = true;
-    startTask(`Waiting for NocoBase to become ready for "${params.envName}"...`);
+    let nextProgressLogAt = startedAt + progressLogIntervalMs;
+    printInfo(`Waiting for NocoBase to become ready for "${params.envName}"...`);
+    const dockerLogFollower = params.verbose && params.containerName ? startDockerLogFollower(params.containerName) : undefined;
     try {
-        while (Date.now() - startedAt < APP_HEALTH_CHECK_TIMEOUT_MS) {
+        while (Date.now() - startedAt < timeoutMs) {
             const result = await requestAppHealthCheck({
                 healthCheckUrl,
                 fetchImpl: params.fetchImpl,
+                requestTimeoutMs: params.requestTimeoutMs,
             });
             if (result.ok) {
-                stopTask();
-                spinnerActive = false;
                 return;
             }
             lastMessage = result.message;
-            const elapsedSeconds = Math.max(1, Math.floor((Date.now() - startedAt) / 1000));
-            updateTask(`Waiting for NocoBase to become ready for "${params.envName}"... (${elapsedSeconds}s elapsed, last status: ${lastMessage})`);
-            await sleep(APP_HEALTH_CHECK_INTERVAL_MS);
+            const now = Date.now();
+            if (now >= nextProgressLogAt) {
+                const elapsedSeconds = Math.max(1, Math.floor((now - startedAt) / 1000));
+                printInfo(`Still waiting for "${params.envName}"... (${elapsedSeconds}s elapsed)`);
+                while (nextProgressLogAt <= now) {
+                    nextProgressLogAt += progressLogIntervalMs;
+                }
+            }
+            const remainingMs = timeoutMs - (Date.now() - startedAt);
+            if (remainingMs <= 0) {
+                break;
+            }
+            await sleep(Math.min(intervalMs, remainingMs));
         }
+        const hints = [
+            params.logHint,
+            params.containerName ? `docker logs ${params.containerName}` : undefined,
+        ].filter(Boolean);
+        const hintText = hints.length > 0 ? ` ${hints.join(' ')}` : '';
+        throw new AppHealthCheckError(`NocoBase did not become ready in time for "${params.envName}". Expected \`${healthCheckUrl}\` to respond with \`ok\`, but the last status was: ${lastMessage}.${hintText}`);
     }
     finally {
-        if (spinnerActive) {
-            stopTask();
-        }
+        await dockerLogFollower?.stop();
     }
-    const hints = [
-        params.logHint,
-        params.containerName ? `docker logs ${params.containerName}` : undefined,
-    ].filter(Boolean);
-    const hintText = hints.length > 0 ? ` ${hints.join(' ')}` : '';
-    throw new AppHealthCheckError(`NocoBase did not become ready in time for "${params.envName}". Expected \`${healthCheckUrl}\` to respond with \`ok\`, but the last status was: ${lastMessage}.${hintText}`);
 }

package/dist/lib/app-managed-resources.js

@@ -82,7 +82,7 @@ function formatSavedDockerSettingsIncomplete(envName, missing) {
     return [
         `Can't start NocoBase for "${envName}" yet.`,
         `The saved Docker settings for this env are incomplete. Missing: ${missing.join(', ')}.`,
-        'Re-run `nb init` or `nb env add` to refresh this env config, then try again.',
+        `Re-run \`nb init --ui --env ${envName}\` to refresh this env config, then try again.`,
     ].join('\n');
 }
 function formatDockerAppRecreateFailure(envName, message) {

package/dist/lib/app-runtime.js

@@ -110,10 +110,10 @@ export function formatMissingManagedAppEnvMessage(envName) {
     if (requested) {
         return [
             `Env "${requested}" is not configured in this workspace.`,
-            `If you want to create a new NocoBase AI environment, run \`nb init --env ${requested}\` first.`,
+            `If you want to create a new NocoBase AI environment, run \`nb init --ui --env ${requested}\` first.`,
         ].join('\n');
     }
-    return 'No NocoBase env is configured yet. Run `nb init` to create one first.';
+    return 'No NocoBase env is configured yet. Run `nb init --ui` to create one first.';
 }
 export async function runLocalNocoBaseCommand(runtime, args, options) {
     const envVars = await buildRuntimeEnvVars(runtime);

package/dist/lib/auth-store.js

@@ -8,7 +8,8 @@
  */
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { resolveCliHomeDir, resolveConfiguredEnvPath, resolveEnvRelativePath, } from './cli-home.js';
+import { resolveCliHomeDir, resolveConfiguredEnvPath, resolveEnvRelativePath } from './cli-home.js';
+import { normalizeCliLocale } from './cli-locale.js';
 import { cleanupCurrentSessionAfterEnvRemoval, resolveEffectiveCurrentEnv, setSessionCurrentEnv, } from './session-store.js';
 function normalizeStoredEnvKind(value) {
     const kind = String(value ?? '').trim();
@@ -24,13 +25,27 @@ function normalizeOptionalString(value) {
     const normalized = String(value ?? '').trim();
     return normalized || undefined;
 }
+function normalizeOptionalCliLocale(value) {
+    const normalized = normalizeOptionalString(value);
+    if (!normalized) {
+        return undefined;
+    }
+    return normalizeCliLocale(normalized);
+}
+function normalizeOptionalCliUpdatePolicy(value) {
+    const normalized = normalizeOptionalString(value);
+    if (normalized === 'prompt' || normalized === 'auto' || normalized === 'off') {
+        return normalized;
+    }
+    return undefined;
+}
 export function readEnvApiBaseUrl(config) {
     if (!config) {
         return undefined;
     }
-    return (normalizeOptionalString(config.apiBaseUrl)
-        ?? normalizeOptionalString(config.baseUrl)
-        ?? normalizeOptionalString(config.apibaseUrl));
+    return (normalizeOptionalString(config.apiBaseUrl) ??
+        normalizeOptionalString(config.baseUrl) ??
+        normalizeOptionalString(config.apibaseUrl));
 }
 export function resolveEnvKind(config) {
     if (!config) {
@@ -70,9 +85,13 @@ function normalizeEnvConfigEntry(entry) {
 }
 function normalizeAuthConfig(config) {
     const settings = config.settings ?? {};
+    const locale = normalizeOptionalCliLocale(settings.locale);
+    const updatePolicy = normalizeOptionalCliUpdatePolicy(settings.update?.policy);
     return {
         name: config.name || config.dockerResourcePrefix,
         settings: {
+            ...(locale ? { locale } : {}),
+            ...(updatePolicy ? { update: { policy: updatePolicy } } : {}),
             ...(settings.license?.pkgUrl ? { license: { pkgUrl: normalizeOptionalString(settings.license.pkgUrl) } } : {}),
             ...(settings.docker?.network || settings.docker?.containerPrefix
                 ? {
@@ -84,8 +103,19 @@ function normalizeAuthConfig(config) {
                     },
                 }
                 : {}),
+            ...(settings.bin?.docker || settings.bin?.git || settings.bin?.yarn
+                ? {
+                    bin: {
+                        ...(settings.bin?.docker ? { docker: normalizeOptionalString(settings.bin.docker) } : {}),
+                        ...(settings.bin?.git ? { git: normalizeOptionalString(settings.bin.git) } : {}),
+                        ...(settings.bin?.yarn ? { yarn: normalizeOptionalString(settings.bin.yarn) } : {}),
+                    },
+                }
+                : {}),
         },
-        lastEnv: config.lastEnv || config.currentEnv || 'default',
+        lastEnv: config.lastEnv ||
+            config.currentEnv ||
+            'default',
         envs: Object.fromEntries(Object.entries(config.envs || {}).map(([envName, entry]) => [envName, normalizeEnvConfigEntry(entry) ?? {}])),
     };
 }
@@ -222,10 +252,11 @@ export class Env {
 export async function getEnv(envName, options = {}) {
     const { config: snapshot, ...loadOptions } = options;
     const config = snapshot ?? (await loadAuthConfig(loadOptions));
-    const resolved = envName?.trim() || (await resolveEffectiveCurrentEnv(Object.keys(config.envs).sort(), {
-        scope: loadOptions.scope,
-        lastEnv: config.lastEnv,
-    }));
+    const resolved = envName?.trim() ||
+        (await resolveEffectiveCurrentEnv(Object.keys(config.envs).sort(), {
+            scope: loadOptions.scope,
+            lastEnv: config.lastEnv,
+        }));
     const envConfig = config.envs[resolved];
     if (!envConfig) {
         return undefined;
@@ -260,37 +291,40 @@ async function writeEnv(envName, updater, options = {}) {
     await saveAuthConfig(config, options);
 }
 function normalizeConfiguredAuthType(value) {
-    return value === 'token' || value === 'oauth' ? value : undefined;
+    return value === 'basic' || value === 'token' || value === 'oauth' ? value : undefined;
 }
 export function resolveConfiguredAuthType(config) {
     return normalizeConfiguredAuthType(config?.authType) ?? normalizeConfiguredAuthType(config?.auth?.type);
 }
 export async function upsertEnv(envName, config, options = {}) {
     await writeEnv(envName, (previous) => {
-        const { apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, accessToken, authType, ...rest } = config;
+        const { apiBaseUrl: _apiBaseUrl, baseUrl: _baseUrl, apibaseUrl: _legacyApiBaseUrl, accessToken, authType, authUsername, ...rest } = config;
         const nextApiBaseUrl = readEnvApiBaseUrl(config);
         const previousApiBaseUrl = readEnvApiBaseUrl(previous);
         const baseUrlChanged = previousApiBaseUrl !== nextApiBaseUrl;
         const previousAuthType = resolveConfiguredAuthType(previous);
         const requestedAuthType = normalizeConfiguredAuthType(authType);
         const nextAuthType = requestedAuthType ?? (accessToken ? 'token' : previousAuthType);
+        const nextAuthUsername = nextAuthType === 'basic' ? normalizeOptionalString(authUsername) ?? previous?.authUsername : undefined;
         const nextAuth = accessToken
             ? {
                 type: 'token',
                 accessToken,
             }
-            : nextAuthType === 'token' || baseUrlChanged || previous?.auth?.type === 'token'
-                ? undefined
-                : previous?.auth;
+            : nextAuthType === 'oauth' && !baseUrlChanged && previous?.auth?.type === 'oauth'
+                ? previous.auth
+                : undefined;
         const authChanged = !areAuthConfigsEquivalent(previous?.auth, nextAuth);
         const authTypeChanged = previousAuthType !== nextAuthType;
+        const authUsernameChanged = previous?.authUsername !== nextAuthUsername;
         return {
             ...previous,
             apiBaseUrl: nextApiBaseUrl,
             authType: nextAuthType,
+            authUsername: nextAuthUsername,
             auth: nextAuth,
             ...rest,
-            runtime: baseUrlChanged || authChanged || authTypeChanged ? undefined : previous?.runtime,
+            runtime: baseUrlChanged || authChanged || authTypeChanged || authUsernameChanged ? undefined : previous?.runtime,
         };
     }, options);
 }
@@ -302,22 +336,25 @@ export async function updateEnvConnection(envName, updates, options = {}) {
         const previousAuthType = resolveConfiguredAuthType(previous);
         const requestedAuthType = normalizeConfiguredAuthType(updates.authType);
         const nextAuthType = requestedAuthType ?? (updates.accessToken ? 'token' : previousAuthType);
+        const nextAuthUsername = nextAuthType === 'basic' ? normalizeOptionalString(updates.authUsername) ?? previous?.authUsername : undefined;
         const nextAuth = updates.accessToken
             ? {
                 type: 'token',
                 accessToken: updates.accessToken,
             }
-            : nextAuthType === 'token' || baseUrlChanged || previous?.auth?.type === 'token'
-                ? undefined
-                : previous?.auth;
+            : nextAuthType === 'oauth' && !baseUrlChanged && previous?.auth?.type === 'oauth'
+                ? previous.auth
+                : undefined;
         const authChanged = !areAuthConfigsEquivalent(previous?.auth, nextAuth);
         const authTypeChanged = previousAuthType !== nextAuthType;
+        const authUsernameChanged = previous?.authUsername !== nextAuthUsername;
         return {
             ...previous,
             ...(nextApiBaseUrl !== undefined ? { apiBaseUrl: nextApiBaseUrl } : {}),
             authType: nextAuthType,
+            authUsername: nextAuthUsername,
             auth: nextAuth,
-            runtime: baseUrlChanged || authChanged || authTypeChanged ? undefined : previous?.runtime,
+            runtime: baseUrlChanged || authChanged || authTypeChanged || authUsernameChanged ? undefined : previous?.runtime,
         };
     }, options);
 }

package/dist/lib/backup.js

@@ -62,14 +62,14 @@ export async function resolveBackupTargetEnv(requestedEnv) {
     const { envs } = await listEnvs({ scope });
     const configuredEnvNames = Object.keys(envs);
     if (!configuredEnvNames.length) {
-        throw new Error('No env is configured. Run `nb env add <name> --api-base-url <url>` first.');
+        throw new Error('No env is configured. Run `nb init --ui` first.');
     }
     if (requestedEnv?.trim()) {
-        throw new Error(`Env "${envName}" is not configured. Run \`nb env add ${envName} --api-base-url <url>\` first.`);
+        throw new Error(`Env "${envName}" is not configured. Run \`nb init --ui --env ${envName}\` first.`);
     }
     throw new Error([
         `Current env "${envName}" is not configured.`,
-        'Switch to an existing env with `nb env use <name>`, or add one with `nb env add <name> --api-base-url <url>`.',
+        `Switch to an existing env with \`nb env use <name>\`, or run \`nb init --ui --env ${envName}\` to create or connect it.`,
     ].join('\n'));
 }
 export async function ensureBackupRuntimeCommands(params) {

package/dist/lib/bootstrap.js

@@ -254,25 +254,31 @@ export function formatSwaggerSchemaError(response, context) {
         })
             .join('\n');
         const envLabel = context.envName ? ` for env "${context.envName}"` : '';
+        const tokenHint = context.envName
+            ? `Update the API key with \`nb env update ${context.envName} --token <api-key>\`, log in with \`nb env auth ${context.envName}\`, or rerun the command with \`--access-token <api-key>\`.`
+            : 'Update the API key with `nb env update <name> --token <api-key>`, log in with `nb env auth <name>`, or rerun the command with `--access-token <api-key>`.';
         const commandHint = context.commandToken
-            ? `If \`${context.commandToken}\` is a runtime command, refresh the runtime after updating the token with \`nb env update\`. If it is a typo, run \`nb --help\` to inspect available commands.`
-            : 'Run `nb --help` to inspect built-in commands, then refresh runtime commands with `nb env update` after updating the token.';
+            ? `If \`${context.commandToken}\` is a runtime command, retry it after updating the token. If it is a typo, run \`nb --help\` to inspect available commands.`
+            : 'Run `nb --help` to inspect built-in commands, then retry the original command after updating the token.';
         return [
             `Authentication failed while loading the command runtime from \`swagger:get\`${envLabel}.`,
             `Base URL: ${context.baseUrl}`,
             details,
-            'Update the API key with `nb env add <name> --api-base-url <url> --auth-type token --access-token <api-key>`, log in with `nb env auth <name>`, or rerun the command with `--access-token <api-key>`.',
+            tokenHint,
             commandHint,
         ].join('\n');
     }
     if (isNetworkFetchFailure(response)) {
         const rawMessage = response.data?.error?.message || 'fetch failed';
+        const updateConnectionHint = context.envName
+            ? `If you recently changed the server address, update env "${context.envName}" with \`nb env update ${context.envName} --api-base-url <url>\` and retry the original command.`
+            : 'If you recently changed the server address, update the saved env connection with `nb env update <name> --api-base-url <url>` and retry the original command.';
         return [
             'Failed to reach the NocoBase server while loading the command runtime from `swagger:get`.',
             `Base URL: ${context.baseUrl}`,
             `Network error: ${rawMessage}`,
             'Check that the NocoBase app is running, the base URL is correct, and the server is reachable from this machine.',
-            'If you recently changed the server address, update it with `nb env add <name> --api-base-url <url>` and retry `nb env update`.',
+            updateConnectionHint,
             'Use `nb env list` to inspect the current env configuration.',
         ].join('\n');
     }
@@ -282,7 +288,7 @@ export function formatMissingRuntimeEnvError(commandToken) {
     if (!commandToken) {
         return [
             'No env is configured for runtime commands.',
-            'Run `nb env add <name> --api-base-url <url>` first.',
+            'Run `nb init --ui` first.',
             'If you configure multiple environments later, switch with `nb env use <name>`.',
         ].join('\n');
     }
@@ -290,7 +296,7 @@ export function formatMissingRuntimeEnvError(commandToken) {
         `Unable to resolve runtime command \`${commandToken}\`.`,
         'No env is configured, so the CLI cannot load runtime commands from `swagger:get`.',
         'If this is a built-in command or a typo, run `nb --help` to inspect available commands.',
-        'If this should be an application runtime command, run `nb env add <name> --api-base-url <url>` and then `nb env update`.',
+        'If this should be an application runtime command, run `nb init --ui` to create or connect a NocoBase app first.',
     ].join('\n');
 }
 export async function ensureRuntimeFromArgv(argv, options) {
@@ -366,8 +372,8 @@ export async function updateEnvRuntime(options) {
         throw new Error([
             env
                 ? `Env "${envName}" is missing a base URL.`
-                : `Env "${envName}" is not configured. Run \`nb env add ${envName}\` first.`,
-            env ? 'Update it with `nb env add <name> --api-base-url <url>` first.' : '',
+                : `Env "${envName}" is not configured. Run \`nb init --ui --env ${envName}\` first.`,
+            env ? `Update env "${envName}" with \`nb env update ${envName} --api-base-url <url>\` first.` : '',
         ]
             .filter(Boolean)
             .join('\n'));

package/dist/lib/cli-config.js

@@ -8,13 +8,24 @@
  */
 import { loadExactAuthConfig, saveAuthConfig } from './auth-store.js';
 import { resolveDefaultConfigScope } from './cli-home.js';
+import { CLI_LOCALE_FLAG_OPTIONS, normalizeCliLocale, resolveCliLocale } from './cli-locale.js';
 export const DEFAULT_LICENSE_PKG_URL = 'https://pkg.nocobase.com/';
 export const DEFAULT_DOCKER_NETWORK = 'nocobase';
 export const DEFAULT_DOCKER_CONTAINER_PREFIX = 'nb';
+export const DEFAULT_DOCKER_BIN = 'docker';
+export const DEFAULT_GIT_BIN = 'git';
+export const DEFAULT_YARN_BIN = 'yarn';
+export const CLI_UPDATE_POLICY_OPTIONS = ['prompt', 'auto', 'off'];
+export const DEFAULT_UPDATE_POLICY = 'prompt';
 export const SUPPORTED_CLI_CONFIG_KEYS = [
+    'locale',
+    'update.policy',
     'license.pkg-url',
     'docker.network',
     'docker.container-prefix',
+    'bin.docker',
+    'bin.git',
+    'bin.yarn',
 ];
 function trimValue(value) {
     const text = String(value ?? '').trim();
@@ -34,13 +45,30 @@ export function assertSupportedCliConfigKey(value) {
     }
     return value;
 }
+export function normalizeCliUpdatePolicy(value) {
+    const normalized = trimValue(value);
+    if (!normalized) {
+        return undefined;
+    }
+    return CLI_UPDATE_POLICY_OPTIONS.includes(normalized) ? normalized : undefined;
+}
 function cloneSettings(config) {
     return {
+        ...(config.settings?.locale ? { locale: trimValue(config.settings.locale) } : {}),
+        update: config.settings?.update ? { ...config.settings.update } : undefined,
         license: config.settings?.license ? { ...config.settings.license } : undefined,
         docker: config.settings?.docker ? { ...config.settings.docker } : undefined,
+        bin: config.settings?.bin ? { ...config.settings.bin } : undefined,
     };
 }
 function pruneSettings(config) {
+    if (config.settings && !trimValue(config.settings.locale)) {
+        delete config.settings.locale;
+    }
+    const update = config.settings?.update;
+    if (update && !normalizeCliUpdatePolicy(update.policy)) {
+        delete config.settings?.update;
+    }
     const license = config.settings?.license;
     if (license && !trimValue(license.pkgUrl)) {
         delete config.settings?.license;
@@ -49,34 +77,61 @@ function pruneSettings(config) {
     if (docker && !trimValue(docker.network) && !trimValue(docker.containerPrefix)) {
         delete config.settings?.docker;
     }
-    if (config.settings
-        && !config.settings.license
-        && !config.settings.docker) {
+    const bin = config.settings?.bin;
+    if (bin && !trimValue(bin.docker) && !trimValue(bin.git) && !trimValue(bin.yarn)) {
+        delete config.settings?.bin;
+    }
+    if (config.settings &&
+        !config.settings.locale &&
+        !config.settings.update &&
+        !config.settings.license &&
+        !config.settings.docker &&
+        !config.settings.bin) {
         delete config.settings;
     }
 }
 export function getExplicitCliConfigValue(config, key) {
     switch (key) {
+        case 'locale':
+            return trimValue(config.settings?.locale);
+        case 'update.policy':
+            return normalizeCliUpdatePolicy(config.settings?.update?.policy);
         case 'license.pkg-url':
             return trimValue(config.settings?.license?.pkgUrl);
         case 'docker.network':
             return trimValue(config.settings?.docker?.network);
         case 'docker.container-prefix':
             return trimValue(config.settings?.docker?.containerPrefix);
+        case 'bin.docker':
+            return trimValue(config.settings?.bin?.docker);
+        case 'bin.git':
+            return trimValue(config.settings?.bin?.git);
+        case 'bin.yarn':
+            return trimValue(config.settings?.bin?.yarn);
     }
 }
 export function getEffectiveCliConfigValue(config, key) {
     const explicit = getExplicitCliConfigValue(config, key);
-    if (explicit) {
+    if (explicit && key !== 'locale') {
         return explicit;
     }
     switch (key) {
+        case 'locale':
+            return resolveCliLocale(undefined, { configuredLocale: trimValue(config.settings?.locale) });
+        case 'update.policy':
+            return explicit ?? DEFAULT_UPDATE_POLICY;
         case 'license.pkg-url':
             return DEFAULT_LICENSE_PKG_URL;
         case 'docker.network':
             return trimValue(config.name) || DEFAULT_DOCKER_NETWORK;
         case 'docker.container-prefix':
             return trimValue(config.name) || DEFAULT_DOCKER_CONTAINER_PREFIX;
+        case 'bin.docker':
+            return DEFAULT_DOCKER_BIN;
+        case 'bin.git':
+            return DEFAULT_GIT_BIN;
+        case 'bin.yarn':
+            return DEFAULT_YARN_BIN;
     }
 }
 export function normalizeCliConfigValue(key, value) {
@@ -87,6 +142,20 @@ export function normalizeCliConfigValue(key, value) {
     if (key === 'license.pkg-url') {
         return normalized.replace(/\/+$/, '') + '/';
     }
+    if (key === 'locale') {
+        const locale = normalizeCliLocale(normalized);
+        if (!locale) {
+            throw new Error(`Config key "${key}" must be one of: ${CLI_LOCALE_FLAG_OPTIONS.join(', ')}`);
+        }
+        return locale;
+    }
+    if (key === 'update.policy') {
+        const policy = normalizeCliUpdatePolicy(normalized);
+        if (!policy) {
+            throw new Error(`Config key "${key}" must be one of: ${CLI_UPDATE_POLICY_OPTIONS.join(', ')}`);
+        }
+        return policy;
+    }
     return normalized;
 }
 export async function loadCliConfig(options = {}) {
@@ -113,6 +182,15 @@ export async function setCliConfigValue(key, value, options = {}) {
     const normalized = normalizeCliConfigValue(key, value);
     config.settings = cloneSettings(config);
     switch (key) {
+        case 'locale':
+            config.settings.locale = normalized;
+            break;
+        case 'update.policy':
+            config.settings.update = {
+                ...(config.settings.update ?? {}),
+                policy: normalized,
+            };
+            break;
         case 'license.pkg-url':
             config.settings.license = {
                 ...(config.settings.license ?? {}),
@@ -131,6 +209,24 @@ export async function setCliConfigValue(key, value, options = {}) {
                 containerPrefix: normalized,
             };
             break;
+        case 'bin.docker':
+            config.settings.bin = {
+                ...(config.settings.bin ?? {}),
+                docker: normalized,
+            };
+            break;
+        case 'bin.git':
+            config.settings.bin = {
+                ...(config.settings.bin ?? {}),
+                git: normalized,
+            };
+            break;
+        case 'bin.yarn':
+            config.settings.bin = {
+                ...(config.settings.bin ?? {}),
+                yarn: normalized,
+            };
+            break;
     }
     pruneSettings(config);
     await saveAuthConfig(config, scope);
@@ -145,6 +241,14 @@ export async function deleteCliConfigValue(key, options = {}) {
     }
     config.settings = cloneSettings(config);
     switch (key) {
+        case 'locale':
+            delete config.settings.locale;
+            break;
+        case 'update.policy':
+            if (config.settings.update) {
+                delete config.settings.update.policy;
+            }
+            break;
         case 'license.pkg-url':
             if (config.settings.license) {
                 delete config.settings.license.pkgUrl;
@@ -160,6 +264,21 @@ export async function deleteCliConfigValue(key, options = {}) {
                 delete config.settings.docker.containerPrefix;
             }
             break;
+        case 'bin.docker':
+            if (config.settings.bin) {
+                delete config.settings.bin.docker;
+            }
+            break;
+        case 'bin.git':
+            if (config.settings.bin) {
+                delete config.settings.bin.git;
+            }
+            break;
+        case 'bin.yarn':
+            if (config.settings.bin) {
+                delete config.settings.bin.yarn;
+            }
+            break;
     }
     pruneSettings(config);
     await saveAuthConfig(config, scope);
@@ -174,3 +293,17 @@ export async function resolveDockerContainerPrefix(options = {}) {
 export async function resolveLicensePkgUrlFromConfig(options = {}) {
     return await getCliConfigValue('license.pkg-url', options);
 }
+const CONFIGURABLE_COMMAND_KEYS = {
+    docker: 'bin.docker',
+    git: 'bin.git',
+    yarn: 'bin.yarn',
+};
+export function isConfigurableCommandName(value) {
+    return Object.prototype.hasOwnProperty.call(CONFIGURABLE_COMMAND_KEYS, value);
+}
+export async function resolveConfiguredCommandName(commandName, options = {}) {
+    if (!isConfigurableCommandName(commandName)) {
+        return commandName;
+    }
+    return await getCliConfigValue(CONFIGURABLE_COMMAND_KEYS[commandName], options);
+}

package/dist/lib/cli-entry-error.js

@@ -0,0 +1,44 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+export function getCommandPathTokens(argv) {
+    const tokens = [];
+    for (const token of argv) {
+        if (!token) {
+            continue;
+        }
+        if (token.startsWith('-')) {
+            break;
+        }
+        tokens.push(token);
+    }
+    return tokens;
+}
+export function formatCliEntryError(error, argv) {
+    const message = error instanceof Error ? error.message : String(error);
+    const missingCommandMatch = message.match(/^Command (.+) not found\.$/);
+    if (!missingCommandMatch) {
+        return message;
+    }
+    const commandPathTokens = getCommandPathTokens(argv);
+    const attemptedCommand = commandPathTokens.join(' ') || missingCommandMatch[1];
+    const isApiCommand = commandPathTokens[0] === 'api';
+    if (isApiCommand) {
+        const helpCommandTokens = commandPathTokens.length > 2 ? commandPathTokens.slice(0, -1) : ['api'];
+        const helpCommand = `nb ${helpCommandTokens.join(' ')} --help`;
+        return [
+            `Unknown command: \`${attemptedCommand}\`.`,
+            `If this is a built-in command or a typo, run \`${helpCommand}\` to inspect the commands available under that API group.`,
+        ].join('\n');
+    }
+    return [
+        `Unknown command: \`${attemptedCommand}\`.`,
+        'If this is a built-in command or a typo, run `nb --help` to inspect available commands.',
+        `If \`${attemptedCommand}\` should be a runtime command from your NocoBase app, check whether the connected app exposes it, then retry the command.`,
+    ].join('\n');
+}