@nocobase/cli 2.1.0-beta.36 → 2.1.0-beta.37

package/dist/lib/prompt-validators.js

@@ -13,6 +13,7 @@ const API_BASE_URL_EXAMPLE = 'http://localhost:13000/api';
 const ENV_KEY_PATTERN = /^[A-Za-z0-9]+$/;
 const TCP_PORT_EXAMPLE = '13000';
 const API_BASE_URL_REQUEST_TIMEOUT_MS = 5_000;
+const TCP_PORT_PROBE_HOSTS = ['127.0.0.1', '0.0.0.0', '::1'];
 function buildHealthCheckUrl(apiBaseUrl) {
     return `${apiBaseUrl.replace(/\/+$/, '')}/__health_check`;
 }
@@ -119,7 +120,7 @@ export function validateTcpPort(value) {
     }
     return undefined;
 }
-async function canListenOnTcpPort(port) {
+async function canListenOnTcpPortHost(port, host) {
     return await new Promise((resolve) => {
         const server = net.createServer();
         const resolveAndCleanup = (result) => {
@@ -131,15 +132,28 @@ async function canListenOnTcpPort(port) {
                 resolve(result);
             }
         };
-        server.once('error', () => {
+        server.once('error', (error) => {
+            if (error.code === 'EADDRNOTAVAIL' || error.code === 'EAFNOSUPPORT') {
+                resolveAndCleanup(undefined);
+                return;
+            }
             resolveAndCleanup(false);
         });
         server.once('listening', () => {
             resolveAndCleanup(true);
         });
-        server.listen(port, '127.0.0.1');
+        server.listen(port, host);
     });
 }
+async function canListenOnTcpPort(port) {
+    for (const host of TCP_PORT_PROBE_HOSTS) {
+        const result = await canListenOnTcpPortHost(port, host);
+        if (result === false) {
+            return false;
+        }
+    }
+    return true;
+}
 function parseDockerPublishedTcpPorts(output) {
     const ports = new Set();
     for (const line of output.split(/\r?\n/)) {
@@ -210,9 +224,10 @@ async function allocateAvailableTcpPort() {
 }
 export async function findAvailableTcpPort() {
     const dockerPorts = await getDockerPublishedTcpPorts();
-    for (let attempt = 0; attempt < 10; attempt += 1) {
+    for (let attempt = 0; attempt < 20; attempt += 1) {
         const candidate = await allocateAvailableTcpPort();
-        if (!dockerPorts.has(Number.parseInt(candidate, 10))) {
+        const port = Number.parseInt(candidate, 10);
+        if (!dockerPorts.has(port) && (await canListenOnTcpPort(port))) {
             return candidate;
         }
     }
@@ -228,6 +243,9 @@ export async function validateAvailableTcpPort(value) {
         return formatError;
     }
     const port = parseTcpPort(raw);
+    if (port === undefined) {
+        return translateCli('validators.tcpPort.invalid', { example: TCP_PORT_EXAMPLE });
+    }
     const dockerPorts = await getDockerPublishedTcpPorts();
     if (dockerPorts.has(port)) {
         return translateCli('validators.tcpPort.alreadyInUseByDocker', { port });

package/dist/lib/prompt-web-ui.js

@@ -295,6 +295,10 @@ function computePwcWizardSteps(options, merged, locale) {
 const PWC_FORM_ITEM_EXPLAIN = '<div class="pwc-form-item-explain" data-pwc-explain="1" role="alert" hidden></div>';
 /** Suffix slot for status icon (e.g. fail) — filled by client script. */
 const PWC_FORM_ITEM_SUFFIX = '<span class="pwc-form-item-suffix" data-pwc-suffix="1" aria-hidden="true"></span>';
+/** Password visibility toggle icon (`eye`). */
+const PWC_FORM_EYE_ICON_SVG = `<svg class="pwc-form-toggle__svg" viewBox="0 0 14 14" width="14" height="14" focusable="false" aria-hidden="true"><path fill="currentColor" d="M7 3c-3.14 0-5.67 2.06-6.69 4c1.02 1.94 3.55 4 6.69 4s5.67-2.06 6.69-4C12.67 5.06 10.14 3 7 3zm0 6.8A2.8 2.8 0 1 1 7 4.2a2.8 2.8 0 0 1 0 5.6zm0-1.2A1.6 1.6 0 1 0 7 5.4a1.6 1.6 0 0 0 0 3.2z"/></svg>`;
+/** Password visibility toggle icon (`eye-off`). */
+const PWC_FORM_EYE_OFF_ICON_SVG = `<svg class="pwc-form-toggle__svg" viewBox="0 0 14 14" width="14" height="14" focusable="false" aria-hidden="true"><path fill="currentColor" d="M2.17 1.32l10.51 10.51-.85.85-2.04-2.04A7.37 7.37 0 0 1 7 11C3.86 11 1.33 8.94.31 7c.54-1.02 1.53-2.15 2.84-2.98L1.32 2.17l.85-.85zm1.88 3.58A6.26 6.26 0 0 0 1.69 7c1.02 1.63 3.12 2.8 5.31 2.8c.79 0 1.56-.15 2.25-.43l-1.1-1.1A2.8 2.8 0 0 1 4.88 5l-.83-.1zm5.87 2.48l-.9-.9a2 2 0 0 0-1.68-1.68l-.9-.9a2.8 2.8 0 0 1 3.48 3.48zM7 3c3.14 0 5.67 2.06 6.69 4a8.4 8.4 0 0 1-2.13 2.43l-.84-.84A6.98 6.98 0 0 0 12.31 7C11.29 5.37 9.19 4.2 7 4.2c-.39 0-.77.04-1.14.11l-.98-.98C5.56 3.12 6.27 3 7 3z"/></svg>`;
 function renderPwcRadioOptions(key, def, defaults, hidden, locale) {
     return def.options
         .map((o, index) => {
@@ -322,7 +326,7 @@ function renderPwcRadioOptions(key, def, defaults, hidden, locale) {
     })
         .join('');
 }
-function renderPwcFieldRow(key, def, defaults, show, locale) {
+function renderPwcFieldRow(key, def, defaults, show, locale, uiText) {
     if (!isInputBlock(def)) {
         return '';
     }
@@ -330,13 +334,16 @@ function renderPwcFieldRow(key, def, defaults, show, locale) {
     const hidden = show[key] === false;
     const display = hidden ? 'none' : 'block';
     const itemOpen = (extraClass) => `<div class="pwc-form-item${extraClass ? ` ${extraClass}` : ''}" data-pwc-wrap="${escapeHtml(key)}" data-pwc-field="${escapeHtml(key)}" style="display:${display}">`;
+    const label = `<span class="pwc-form-item-label-text">${'required' in def && def.required
+        ? '<span class="pwc-form-item-required" aria-hidden="true">*</span>'
+        : ''}<span class="pwc-l">${escapeHtml(labelText)}</span></span>`;
     if (def.type === 'text') {
         const req = def.required ? ' required' : '';
         const disabled = hidden ? ' disabled' : '';
         const ph = def.placeholder ? ` placeholder="${escapeHtml(resolveUiText(def.placeholder, locale))}"` : '';
         const v = escapeHtml(String(defaults[key] ?? ''));
         return (itemOpen('') +
-            `<div class="pwc-form-item-label"><span class="pwc-l">${escapeHtml(labelText)}</span></div>` +
+            `<div class="pwc-form-item-label">${label}</div>` +
             `<div class="pwc-form-item-control">` +
             `<div class="pwc-form-item-control-input">` +
             `<div class="pwc-input-affix-wrapper">` +
@@ -350,7 +357,7 @@ function renderPwcFieldRow(key, def, defaults, show, locale) {
         const checked = defaults[key] === true ? ' checked' : '';
         const disabled = hidden ? ' disabled' : '';
         return (itemOpen('pwc-form-item--bool') +
-            `<div class="pwc-bool-wrap"><label><input class="pwc-bool-input" name="${escapeHtml(key)}" type="checkbox" value="1"${checked}${disabled} /> <span class="pwc-l">${escapeHtml(labelText)}</span></label></div>` +
+            `<div class="pwc-bool-wrap"><label><input class="pwc-bool-input" name="${escapeHtml(key)}" type="checkbox" value="1"${checked}${disabled} /> ${label}</label></div>` +
             PWC_FORM_ITEM_EXPLAIN +
             `</div>`);
     }
@@ -358,7 +365,7 @@ function renderPwcFieldRow(key, def, defaults, show, locale) {
         if (def.variant === 'radio') {
             const opts = renderPwcRadioOptions(key, def, defaults, hidden, locale);
             return (itemOpen('') +
-                `<div class="pwc-form-item-label"><span class="pwc-l">${escapeHtml(labelText)}</span></div>` +
+                `<div class="pwc-form-item-label">${label}</div>` +
                 `<div class="pwc-form-item-control">` +
                 `<div class="pwc-form-item-control-input">` +
                 `<div class="pwc-radio-group" role="radiogroup" aria-label="${escapeHtml(labelText)}">` +
@@ -379,7 +386,7 @@ function renderPwcFieldRow(key, def, defaults, show, locale) {
         const req = def.required ? ' required' : '';
         const disabled = hidden ? ' disabled' : '';
         return (itemOpen('') +
-            `<div class="pwc-form-item-label"><span class="pwc-l">${escapeHtml(labelText)}</span></div>` +
+            `<div class="pwc-form-item-label">${label}</div>` +
             `<div class="pwc-form-item-control">` +
             `<div class="pwc-form-item-control-input">` +
             `<div class="pwc-input-affix-wrapper pwc-input-affix-wrapper--select">` +
@@ -393,13 +400,15 @@ function renderPwcFieldRow(key, def, defaults, show, locale) {
         const req = def.required ? ' required' : '';
         const disabled = hidden ? ' disabled' : '';
         const v = escapeHtml(String(defaults[key] ?? ''));
+        const showPassword = escapeHtml(uiText?.showPassword ?? 'Show password');
         return (itemOpen('') +
-            `<div class="pwc-form-item-label"><span class="pwc-l">${escapeHtml(labelText)}</span></div>` +
+            `<div class="pwc-form-item-label">${label}</div>` +
             `<div class="pwc-form-item-control">` +
             `<div class="pwc-form-item-control-input">` +
-            `<div class="pwc-input-affix-wrapper">` +
-            `<input class="pwc-form-input" name="${escapeHtml(key)}" type="password" value="${v}"${req}${disabled} autocomplete="new-password" />` +
+            `<div class="pwc-input-affix-wrapper pwc-input-affix-wrapper--password" data-pwc-password-wrap="1">` +
+            `<input class="pwc-form-input" data-pwc-password-input="1" name="${escapeHtml(key)}" type="password" value="${v}"${req}${disabled} autocomplete="new-password" />` +
             PWC_FORM_ITEM_SUFFIX +
+            `<button class="pwc-password-toggle" type="button" data-pwc-password-toggle="1" aria-label="${showPassword}" title="${showPassword}" aria-pressed="false"${disabled}>${PWC_FORM_EYE_ICON_SVG}</button>` +
             `</div></div>` +
             PWC_FORM_ITEM_EXPLAIN +
             `</div></div>`);
@@ -410,7 +419,7 @@ function renderPwcFieldRow(key, def, defaults, show, locale) {
         const disabled = hidden ? ' disabled' : '';
         const v = String(defaults[key] ?? 0);
         return (itemOpen('') +
-            `<div class="pwc-form-item-label"><span class="pwc-l">${escapeHtml(labelText)}</span></div>` +
+            `<div class="pwc-form-item-label">${label}</div>` +
             `<div class="pwc-form-item-control">` +
             `<div class="pwc-form-item-control-input">` +
             `<div class="pwc-input-affix-wrapper">` +
@@ -517,7 +526,7 @@ function buildPwcFormHtml(catalog, defaults, show, stepDefs, initialStepIndex, t
         for (const key of sd.keys) {
             const def = catalog[key];
             if (def) {
-                out.push(renderPwcFieldRow(key, def, defaults, show, locale));
+                out.push(renderPwcFieldRow(key, def, defaults, show, locale, uiText));
             }
         }
         out.push('</section>');
@@ -707,6 +716,8 @@ function runPromptCatalogWebUIImpl(options) {
         back: t('promptCatalog.web.back'),
         next: t('promptCatalog.web.next'),
         submit: t('promptCatalog.web.submit'),
+        showPassword: t('promptCatalog.web.showPassword'),
+        hidePassword: t('promptCatalog.web.hidePassword'),
         checking: t('promptCatalog.web.checking'),
         sending: t('promptCatalog.web.sending'),
         successTitle: t('promptCatalog.web.successTitle'),
@@ -1213,6 +1224,8 @@ function runPromptCatalogWebUIImpl(options) {
     /* antd Form.Item: label + control + explain — @see https://ant.design/components/form */
     .pwc-form-item { margin: 0 0 24px 0; }
     .pwc-form-item-label { margin: 0; padding: 0; }
+    .pwc-form-item-label-text { display: inline-flex; align-items: flex-start; gap: 4px; }
+    .pwc-form-item-required { color: var(--pwc-form-color-error); font-weight: 600; line-height: 1; margin-top: 2px; }
     .pwc-form-item-control { width: 100%; }
     .pwc-form-item--bool { margin: 0 0 24px 0; }
     .pwc-form-item--bool .pwc-bool-wrap { margin: 0; }
@@ -1226,7 +1239,71 @@ function runPromptCatalogWebUIImpl(options) {
       pointer-events: none;
     }
     .pwc-input-affix-wrapper .pwc-form-input { padding-right: 32px; }
-    .pwc-input-affix-wrapper--select .pwc-form-input { padding-right: 32px; }
+    .pwc-input-affix-wrapper--select::after {
+      content: '';
+      position: absolute;
+      right: 14px;
+      top: 50%;
+      width: 8px;
+      height: 8px;
+      margin-top: -6px;
+      border-right: 2px solid var(--pwc-ad-color-text-description);
+      border-bottom: 2px solid var(--pwc-ad-color-text-description);
+      transform: rotate(45deg);
+      pointer-events: none;
+      transition: border-color 0.2s;
+    }
+    .pwc-input-affix-wrapper--select:hover::after {
+      border-color: var(--pwc-ad-color-text);
+    }
+    .pwc-input-affix-wrapper--select:focus-within::after {
+      border-color: var(--pwc-ad-color-primary);
+    }
+    .pwc-input-affix-wrapper--select .pwc-form-input {
+      padding-right: 56px;
+      appearance: none;
+      -webkit-appearance: none;
+      -moz-appearance: none;
+      background-image: none;
+    }
+    .pwc-input-affix-wrapper--select .pwc-form-item-suffix { right: 36px; }
+    .pwc-input-affix-wrapper--password .pwc-form-input { padding-right: 68px; }
+    .pwc-input-affix-wrapper--password .pwc-form-item-suffix { right: 39px; }
+    .pwc-password-toggle {
+      position: absolute;
+      z-index: 1;
+      right: 8px;
+      top: 50%;
+      width: 24px;
+      height: 24px;
+      margin: 0;
+      padding: 0;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      border: none;
+      border-radius: 6px;
+      background: transparent;
+      color: var(--pwc-ad-color-text-description);
+      cursor: pointer;
+      transform: translateY(-50%);
+      transition: color 0.2s, background 0.2s, box-shadow 0.2s;
+    }
+    .pwc-password-toggle:hover {
+      color: var(--pwc-ad-color-text);
+      background: color-mix(in srgb, var(--pwc-ad-color-text) 6%, transparent);
+    }
+    .pwc-password-toggle:focus-visible {
+      outline: none;
+      box-shadow: 0 0 0 2px color-mix(in srgb, var(--pwc-ad-color-primary) 16%, transparent);
+    }
+    .pwc-password-toggle:disabled {
+      color: color-mix(in srgb, var(--pwc-ad-color-text-description) 60%, transparent);
+      cursor: not-allowed;
+      background: transparent;
+      box-shadow: none;
+    }
+    .pwc-form-toggle__svg { display: block; }
     .pwc-form-item-explain { font-size: 14px; line-height: 1.5715; margin-top: 4px; clear: both; }
     .pwc-form-item-explain[hidden] { display: none !important; }
     .pwc-form-item-explain:not([hidden]) { color: var(--pwc-form-color-error); }
@@ -1257,6 +1334,9 @@ function runPromptCatalogWebUIImpl(options) {
       border-radius: 6px;
       transition: border-color 0.2s, box-shadow 0.2s, background 0.2s;
     }
+    input.pwc-form-input, select.pwc-form-input {
+      height: 40px;
+    }
     input.pwc-form-input:hover, select.pwc-form-input:hover, textarea:hover {
       border-color: var(--pwc-ad-color-primary);
     }
@@ -1411,6 +1491,8 @@ function runPromptCatalogWebUIImpl(options) {
     var pwcErrIcon = ${JSON.stringify(PWC_AD_ALERT_ERROR_ICON_SVG)};
     var pwcOkIcon = ${JSON.stringify(PWC_AD_ALERT_SUCCESS_ICON_SVG)};
     var pwcFieldFail = ${JSON.stringify(PWC_FORM_FAIL_ICON_SVG)};
+    var pwcEyeIcon = ${JSON.stringify(PWC_FORM_EYE_ICON_SVG)};
+    var pwcEyeOffIcon = ${JSON.stringify(PWC_FORM_EYE_OFF_ICON_SVG)};
     var pwcCloseTimer = null;
     var pwcCloseProbeTimer = null;
     var pwcFieldReqSeq = {};
@@ -1468,7 +1550,7 @@ function runPromptCatalogWebUIImpl(options) {
     }
     function pwcSetFieldError(key, message) {
       if (!form || !key) { return; }
-      var wrap = form.querySelector('[data-pwc-field=\"' + String(key) + '\"]');
+      var wrap = form.querySelector('[data-pwc-field="' + String(key) + '"]');
       if (!wrap) { return; }
       var ex = wrap.querySelector('[data-pwc-explain]');
       var suf = wrap.querySelector('[data-pwc-suffix]');
@@ -1506,9 +1588,50 @@ function runPromptCatalogWebUIImpl(options) {
       } catch (e) {}
       return { msg: msg, fk: fk };
     }
+    function pwcSyncPasswordToggle(toggle, input) {
+      if (!toggle || !input) { return; }
+      var visible = input.getAttribute('type') === 'text';
+      var label = visible ? uiText.hidePassword : uiText.showPassword;
+      toggle.setAttribute('aria-label', String(label));
+      toggle.setAttribute('title', String(label));
+      toggle.setAttribute('aria-pressed', visible ? 'true' : 'false');
+      toggle.innerHTML = visible ? pwcEyeOffIcon : pwcEyeIcon;
+    }
+    function pwcInitPasswordToggles() {
+      if (!form) { return; }
+      var toggles = form.querySelectorAll('[data-pwc-password-toggle]');
+      for (var i = 0; i < toggles.length; i++) {
+        (function () {
+          var toggle = toggles[i];
+          var wrap = toggle.parentElement;
+          var input = wrap ? wrap.querySelector('[data-pwc-password-input]') : null;
+          pwcSyncPasswordToggle(toggle, input);
+          toggle.addEventListener('click', function () {
+            if (!input || input.disabled) { return; }
+            var nextType = input.getAttribute('type') === 'text' ? 'password' : 'text';
+            var start = typeof input.selectionStart === 'number' ? input.selectionStart : null;
+            var end = typeof input.selectionEnd === 'number' ? input.selectionEnd : null;
+            input.setAttribute('type', nextType);
+            pwcSyncPasswordToggle(toggle, input);
+            if (typeof input.focus === 'function') {
+              input.focus({ preventScroll: true });
+            }
+            if (
+              start !== null &&
+              end !== null &&
+              typeof input.setSelectionRange === 'function'
+            ) {
+              try {
+                input.setSelectionRange(start, end);
+              } catch (e) {}
+            }
+          });
+        })();
+      }
+    }
     function pwcSetFieldDirty(key, dirty) {
       if (!form || !key) { return; }
-      var wrap = form.querySelector('[data-pwc-field=\"' + String(key) + '\"]');
+      var wrap = form.querySelector('[data-pwc-field="' + String(key) + '"]');
       if (!wrap) { return; }
       if (dirty) {
         wrap.setAttribute('data-pwc-dirty', '1');
@@ -1518,7 +1641,7 @@ function runPromptCatalogWebUIImpl(options) {
     }
     function pwcIsFieldDirty(key) {
       if (!form || !key) { return false; }
-      var wrap = form.querySelector('[data-pwc-field=\"' + String(key) + '\"]');
+      var wrap = form.querySelector('[data-pwc-field="' + String(key) + '"]');
       return !!(wrap && wrap.getAttribute('data-pwc-dirty') === '1');
     }
     function getControl(formEl, k) {
@@ -1609,7 +1732,7 @@ function runPromptCatalogWebUIImpl(options) {
             var wasHidden = w.style.display === 'none';
             var hidden = k != null && sh[k] === false;
             w.style.display = hidden ? 'none' : 'block';
-            var ctrls = w.querySelectorAll('input, select, textarea');
+            var ctrls = w.querySelectorAll('input, select, textarea, button[data-pwc-password-toggle]');
             for (var i = 0; i < ctrls.length; i++) {
               ctrls[i].disabled = hidden || ctrls[i].getAttribute('data-pwc-static-disabled') === '1';
             }
@@ -1633,7 +1756,7 @@ function runPromptCatalogWebUIImpl(options) {
       }
       for (var i = 0; i < st.keys.length; i++) {
         var key = st.keys[i];
-        var wrap = form.querySelector('[data-pwc-wrap=\"' + String(key) + '\"]');
+        var wrap = form.querySelector('[data-pwc-wrap="' + String(key) + '"]');
         if (wrap && wrap.style.display !== 'none') {
           return true;
         }
@@ -1771,7 +1894,7 @@ function runPromptCatalogWebUIImpl(options) {
       }
       for (var j = 0; j < st.keys.length; j++) {
         var k = st.keys[j];
-        var w = form.querySelector('[data-pwc-wrap=\"' + k + '\"]');
+        var w = form.querySelector('[data-pwc-wrap="' + k + '"]');
         if (!w || w.style.display === 'none') { continue; }
         var inp = getControl(form, k);
         if (inp == null) { continue; }
@@ -1796,7 +1919,7 @@ function runPromptCatalogWebUIImpl(options) {
     }
     function pwcValidateField(key) {
       if (!form || !key || pwcValField == null) { return Promise.resolve(); }
-      var wrap = form.querySelector('[data-pwc-wrap=\"' + String(key) + '\"]');
+      var wrap = form.querySelector('[data-pwc-wrap="' + String(key) + '"]');
       if (!wrap || wrap.style.display === 'none') { return Promise.resolve(); }
       var reqSeq = (pwcFieldReqSeq[key] || 0) + 1;
       pwcFieldReqSeq[key] = reqSeq;
@@ -1898,6 +2021,7 @@ function runPromptCatalogWebUIImpl(options) {
     var pwcNext = document.getElementById('pwcNext');
     if (pwcNext) { pwcNext.addEventListener('click', function () { void pwcTryAdvanceNext(); }); }
     pwcRefreshVisibleSteps();
+    pwcInitPasswordToggles();
     if (form) { setTimeout(function () { reflow(); }, 0); }
     if (form) {
       form.addEventListener('submit', function (e) {
@@ -1934,7 +2058,7 @@ function runPromptCatalogWebUIImpl(options) {
       });
     }
   })();
-  <\/script>
+  </script>
 </body>
 </html>`;
             return page;

package/dist/lib/run-npm.js

@@ -19,9 +19,39 @@ import fsp from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import spawn from 'cross-spawn';
+import { translateCli } from './cli-locale.js';
+import { resolveConfiguredCommandName } from './cli-config.js';
 const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM'];
-function resolveCommandName(name) {
-    return name;
+const PROCESS_TIMEOUT_FORCE_KILL_DELAY_MS = 1000;
+const MISSING_COMMAND_SPECS = {
+    docker: {
+        displayName: 'Docker',
+        configKey: 'bin.docker',
+    },
+    git: {
+        displayName: 'Git',
+        configKey: 'bin.git',
+    },
+    yarn: {
+        displayName: 'Yarn',
+        configKey: 'bin.yarn',
+    },
+};
+async function resolveCommandName(name) {
+    return await resolveConfiguredCommandName(name);
+}
+function createMissingCommandError(name, label, error) {
+    const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : undefined;
+    if (code !== 'ENOENT') {
+        return undefined;
+    }
+    if (!Object.prototype.hasOwnProperty.call(MISSING_COMMAND_SPECS, name)) {
+        return undefined;
+    }
+    const spec = MISSING_COMMAND_SPECS[name];
+    return new Error(translateCli('commands.shared.missingCommand', { action: label, displayName: spec.displayName, configKey: spec.configKey }, {
+        fallback: `Couldn't run \`${label}\` because the ${spec.displayName} executable could not be found. Install ${spec.displayName} or update \`nb config set ${spec.configKey} <path>\` and try again.`,
+    }));
 }
 function pathExists(candidate) {
     try {
@@ -40,8 +70,8 @@ function isDirectory(candidate) {
     }
 }
 function hasLocalNocoBaseBinary(candidate) {
-    return (pathExists(path.join(candidate, 'node_modules', '.bin', 'nocobase-v1'))
-        || pathExists(path.join(candidate, 'node_modules', '.bin', 'nocobase-v1.cmd')));
+    return (pathExists(path.join(candidate, 'node_modules', '.bin', 'nocobase-v1')) ||
+        pathExists(path.join(candidate, 'node_modules', '.bin', 'nocobase-v1.cmd')));
 }
 export function resolveCwd(cwd) {
     const next = cwd ?? process.cwd();
@@ -61,10 +91,7 @@ export function resolveProjectCwd(cwd) {
         throw new Error(`The specified --cwd is not a directory: ${fallback}`);
     }
     let current = hasExplicitInput ? fallback : process.cwd();
-    while (true) {
-        if (hasLocalNocoBaseBinary(current)) {
-            return current;
-        }
+    while (!hasLocalNocoBaseBinary(current)) {
         const parent = path.dirname(current);
         if (parent === current) {
             if (hasExplicitInput) {
@@ -74,12 +101,13 @@ export function resolveProjectCwd(cwd) {
         }
         current = parent;
     }
+    return current;
 }
-export function run(name, args, options) {
+export async function run(name, args, options) {
     const cwd = resolveCwd(options?.cwd);
     const label = options?.errorName ?? name;
-    const command = resolveCommandName(name);
-    return new Promise((resolve, reject) => {
+    const command = await resolveCommandName(name);
+    return await new Promise((resolve, reject) => {
         const child = spawn(command, [...args], {
             stdio: options?.stdio ?? 'inherit',
             cwd,
@@ -104,12 +132,19 @@ export function run(name, args, options) {
             }
         }
         const cleanupSignalForwarding = forwardSignalsToChild(child);
+        const timeoutController = attachProcessTimeout(child, options?.timeoutMs);
         child.once('error', (error) => {
+            timeoutController.cleanup();
             cleanupSignalForwarding();
-            reject(error);
+            reject(createMissingCommandError(name, label, error) ?? error);
         });
         child.once('close', (code, signal) => {
+            timeoutController.cleanup();
             cleanupSignalForwarding();
+            if (timeoutController.didTimeout()) {
+                reject(new Error(`${label} timed out after ${options?.timeoutMs}ms`));
+                return;
+            }
             if (code === 0) {
                 resolve();
                 return;
@@ -122,6 +157,46 @@ export function run(name, args, options) {
         });
     });
 }
+function attachProcessTimeout(child, timeoutMs) {
+    if (!timeoutMs || timeoutMs <= 0) {
+        return {
+            cleanup: () => undefined,
+            didTimeout: () => false,
+        };
+    }
+    let didTimeout = false;
+    let forceKillTimer;
+    const isChildRunning = () => child.exitCode === null && child.signalCode === null;
+    const terminateChild = (signal) => {
+        if (!isChildRunning()) {
+            return;
+        }
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // Ignore kill errors here and let the child close/error handlers surface the failure.
+        }
+    };
+    const timeoutTimer = setTimeout(() => {
+        didTimeout = true;
+        terminateChild('SIGTERM');
+        forceKillTimer = setTimeout(() => {
+            terminateChild('SIGKILL');
+        }, PROCESS_TIMEOUT_FORCE_KILL_DELAY_MS);
+        forceKillTimer.unref?.();
+    }, timeoutMs);
+    timeoutTimer.unref?.();
+    return {
+        cleanup: () => {
+            clearTimeout(timeoutTimer);
+            if (forceKillTimer) {
+                clearTimeout(forceKillTimer);
+            }
+        },
+        didTimeout: () => didTimeout,
+    };
+}
 function forwardSignalsToChild(child) {
     let forwardedSignalCount = 0;
     const listeners = new Map();
@@ -149,10 +224,11 @@ function forwardSignalsToChild(child) {
         }
     };
 }
-export function commandSucceeds(name, args, options) {
+export async function commandSucceeds(name, args, options) {
     const cwd = resolveCwd(options?.cwd);
-    const command = resolveCommandName(name);
-    return new Promise((resolve) => {
+    const label = options?.errorName ?? name;
+    const command = await resolveCommandName(name);
+    return await new Promise((resolve, reject) => {
         const child = spawn(command, [...args], {
             cwd,
             env: {
@@ -162,15 +238,31 @@ export function commandSucceeds(name, args, options) {
             stdio: 'ignore',
             windowsHide: process.platform === 'win32',
         });
-        child.once('error', () => resolve(false));
-        child.once('close', (code) => resolve(code === 0));
+        const timeoutController = attachProcessTimeout(child, options?.timeoutMs);
+        child.once('error', (error) => {
+            timeoutController.cleanup();
+            const missingCommandError = createMissingCommandError(name, label, error);
+            if (missingCommandError) {
+                reject(missingCommandError);
+                return;
+            }
+            resolve(false);
+        });
+        child.once('close', (code) => {
+            timeoutController.cleanup();
+            if (timeoutController.didTimeout()) {
+                resolve(false);
+                return;
+            }
+            resolve(code === 0);
+        });
     });
 }
-export function commandOutput(name, args, options) {
+export async function commandOutput(name, args, options) {
     const cwd = resolveCwd(options?.cwd);
     const label = options?.errorName ?? name;
-    const command = resolveCommandName(name);
-    return new Promise((resolve, reject) => {
+    const command = await resolveCommandName(name);
+    return await new Promise((resolve, reject) => {
         const child = spawn(command, [...args], {
             cwd,
             env: {
@@ -190,8 +282,17 @@ export function commandOutput(name, args, options) {
         child.stderr.on('data', (chunk) => {
             stderr += chunk;
         });
-        child.once('error', reject);
+        const timeoutController = attachProcessTimeout(child, options?.timeoutMs);
+        child.once('error', (error) => {
+            timeoutController.cleanup();
+            reject(createMissingCommandError(name, label, error) ?? error);
+        });
         child.once('close', (code, signal) => {
+            timeoutController.cleanup();
+            if (timeoutController.didTimeout()) {
+                reject(new Error(`${label} timed out after ${options?.timeoutMs}ms`));
+                return;
+            }
             if (code === 0) {
                 resolve(stdout.trim());
                 return;
@@ -216,7 +317,7 @@ async function readCommandOutputFile(filePath) {
 export async function commandOutputViaFile(name, args, options) {
     const cwd = resolveCwd(options?.cwd);
     const label = options?.errorName ?? name;
-    const command = resolveCommandName(name);
+    const command = await resolveCommandName(name);
     const captureDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'nocobase-cli-output-'));
     const stdoutPath = path.join(captureDir, 'stdout.log');
     const stderrPath = path.join(captureDir, 'stderr.log');
@@ -233,8 +334,17 @@ export async function commandOutputViaFile(name, args, options) {
                 stdio: ['ignore', stdoutHandle.fd, stderrHandle.fd],
                 windowsHide: process.platform === 'win32',
             });
-            child.once('error', reject);
+            const timeoutController = attachProcessTimeout(child, options?.timeoutMs);
+            child.once('error', (error) => {
+                timeoutController.cleanup();
+                reject(createMissingCommandError(name, label, error) ?? error);
+            });
             child.once('close', (code, signal) => {
+                timeoutController.cleanup();
+                if (timeoutController.didTimeout()) {
+                    reject(new Error(`${label} timed out after ${options?.timeoutMs}ms`));
+                    return;
+                }
                 resolve({ code, signal });
             });
         });