@neuxnet/neux-cli 0.2.6 → 0.2.8

package/README.md

@@ -45,11 +45,10 @@ NEUX_CLI_KEY_APP_XXX=key_xxx neux debug --project ./miniapp --app-id app_xxx --s
 NEUX_CLI_KEY_APP_XXX=key_xxx neux service-preview --app-id app_xxx --server-url https://miniapp.example.com --json
 NEUX_CLI_KEY_APP_XXX=key_xxx neux submit --app-id app_xxx --server-url https://miniapp.example.com --version-id 123 --json
 NEUX_CLI_KEY_APP_XXX=key_xxx neux status --app-id app_xxx --server-url https://miniapp.example.com --json
-NEUX_CLI_KEY_APP_XXX=key_xxx neux meta --app-id app_xxx --server-url https://miniapp.example.com --json
 NEUX_CLI_KEY_APP_XXX=key_xxx neux audit-status --app-id app_xxx --server-url https://miniapp.example.com --version-id 123 --json
 ```
 
-`init` creates a minimal mini program project from scratch. In a TTY it interactively asks for the project name, App ID, Server URL, and a hidden `CLI Key`. The default Server URL is `https://demo-c.paas.superapp.neuvision.cn`. App ID and Server URL are written to the project; each App ID's CLI Key is stored in the user-level `~/.neux/config.json` and never in project files. Use `neux config set` to change the current project's CLI Key. `build` creates the client `.wgt` delivery artifact. `upload`, `debug`, `service-preview`, `submit`, `status` / `meta`, and `audit-status` use the signed service API when `--provider` is omitted. `debug-preview`, `submit-audit`, `version`, and `wgt` remain compatibility spellings for integrations that already use them. `login` is still provider-backed and unsupported by the signed service. Use `--provider local-file` or a provider module when testing adapter integrations instead of the remote service.
+`init` creates a minimal mini program project from scratch. In a TTY it interactively asks for the project name, App ID, Server URL, and a hidden `CLI Key`. The default Server URL is `https://demo-c.paas.superapp.neuvision.cn`. App ID and Server URL are written to the project; each App ID's CLI Key is stored in the user-level `~/.neux/config.json` and never in project files. Use `neux config set` to change the current project's CLI Key. `build` creates the client `.wgt` delivery artifact. `upload`, `debug`, `service-preview`, `submit`, `status`, and `audit-status` use the signed service API when `--provider` is omitted. `debug-preview`, `submit-audit`, `meta`, `version`, `audit`, and `wgt` remain compatibility spellings for integrations that already use them; compatibility and legacy commands print a deprecation warning to stderr. `preview` and `web` are legacy local preview entrypoints; prefer `dev` for new scripts. `login` is provider-specific, hidden from the default root help, and unsupported by the signed service. Use `--provider local-file` or a provider module when testing adapter integrations instead of the remote service. Run `neux <command> --help` for command-specific options.
 
 The generated project also includes source-backed JSON Schemas under `.vscode/neux-json-schemas/` and registers them in `.vscode/settings.json`. Run `npm run verify:schemas` in the CLI repository to verify that the checked-in schemas and init registration remain aligned. VS Code can therefore provide completion, hover documentation, enum suggestions, and basic validation for `app.json`, page JSON files, `project.config.json`, `project.private.config.json`, and `neux.config.json`. These schemas describe fields consumed by the Neux CLI/compiler; cross-file checks such as page existence and component path resolution remain compiler/CLI validation.
 
@@ -381,7 +380,9 @@ Event names are stable: `build-start`, `build-success`, `build-error`, `ready`,
 
 ## Provider Adapters
 
-Provider commands first create a package artifact, then call the selected provider:
+Provider commands first create a package artifact, then call the selected provider. The
+default signed service does not implement `login`; the command is intentionally hidden
+from the root help and is only useful when a custom provider supplies a `login` method:
 
 ```sh
 neux login --project ./miniapp --provider ./provider.mjs --json

package/README.zh-CN.md

@@ -112,7 +112,6 @@ neux debug --page-path pages/index/index --query foo=bar
 neux upload --preview --changelog "Release notes" --channel test
 neux submit --version-id 123 --channel test
 neux status --json
-neux meta --json
 neux audit-status --version-id 123 --json
 ```
 
@@ -192,16 +191,22 @@ neux config set --key NEW_CLI_KEY
 | `neux upload` | 上传 signed service 体验包 |
 | `neux debug` | 上传调试预览包，并输出 deeplink 与可扫码终端二维码 |
 | `neux submit` | 提交体验版本审核 |
-| `neux status` / `neux meta` | 查询 signed service 版本信息 |
+| `neux status` | 查询 signed service 版本信息 |
 | `neux audit-status` | 查询审核状态 |
 | `neux config doctor` | 诊断 signed service 配置 |
 | `neux config set` | 交互式修改当前项目的 CLI Key |
 | `neux update` | 检查并更新 CLI |
-| `neux --version` / `neux cli-version` | 查看当前安装的 CLI 版本 |
+| `neux --version` | 查看当前安装的 CLI 版本 |
+| `neux cli-version` | 查看详细 CLI 包信息，适合 IDE/CI |
 | `neux compile` | 仅执行内置小程序编译 |
+| `neux pack` | 将已有编译产物打包为本地归档 |
 | `neux wgt` | `neux build` 的兼容别名 |
 
-兼容命令包括 `debug-preview`、`service-preview`、`submit-audit`、`version`、`audit`、`preview`、`web`。新脚本优先使用 `build`、`dev`、`debug`、`upload`、`submit`。
+`service-preview` 和 `audit-status` 属于高级服务命令。`debug-preview`、`submit-audit`、
+`meta`、`version`、`audit` 和 `wgt` 是兼容命令；`preview`、`web` 是旧版本地预览
+入口。调用兼容命令或旧版命令时，CLI 会向 stderr 输出弃用提示；新脚本优先使用
+`build`、`dev`、`debug`、`upload`、`submit`、`status`。
+可使用 `neux <command> --help` 查看命令级选项。
 
 ## 更新 CLI
 
@@ -315,7 +320,6 @@ neux submit --version-id 123 --channel test
 
 ```sh
 neux status --json
-neux meta --json
 ```
 
 查询审核状态：
@@ -457,6 +461,8 @@ neux preview --json --stay
 ## Provider 适配器
 
 默认不传 `--provider` 时，`upload`、`debug`、`submit` 等命令使用 signed service。
+默认 signed service 不实现 `login`；`login` 不会出现在根命令帮助中，仅在自定义
+Provider 实现 `login` 时才有意义。
 
 如果要测试自定义适配器，可以传入 provider 模块：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuxnet/neux-cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Standalone CLI and Node API for Neux mini program build, pack, preview, and CI automation.",
   "type": "module",
   "bin": {

package/src/bin/cli.js

@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process'
 import { buildProject, createLifecycleEvent, createProjectWatcher, DEFAULT_SERVER_URL, getCliPackageInfo, getCliVersion, initProject, inspectProject, maybeAutoUpdateCli, packProject, saveCliKey, startDev, startPreview, startWeb, updateCli } from '../index.js'
 import { DiminaCliError, toErrorPayload } from '../core/errors.js'
 import { brand } from '../core/brand.js'
+import { help, rootHelp, warnIfDeprecated } from '../core/help.js'
 import { runProviderCommand, unsupportedProviderCommand } from '../providers/upload.js'
 import { resolveServiceConfig, resolveServiceConfigDiagnostics } from '../providers/service-config.js'
 import { renderQrPng, renderTerminalQr } from '../core/terminal-qr.js'
@@ -54,90 +55,6 @@ function createSessionSignalController() {
 import { resolveLocale, translate } from '../core/i18n.js'
 import { promptLine } from '../core/prompts.js'
 
-function help(locale = 'en') {
-  return `${translate(locale, 'usage')}: ${brand.commandName} <command> [options]
-
-${translate(locale, 'commands')}:
-  init      Create a new mini program project
-  inspect   Read mini program metadata
-  dev       Compile, open the H5 container, watch files, and live reload
-  build     Build and create a client .wgt package in dist/release/
-  upload    Upload a signed service trial package
-  debug     Upload a signed debug preview package and print a QR code
-  submit    Submit a signed service trial version for audit
-  status    Query signed service version information
-  meta      Alias of status for signed service version metadata
-  config    Diagnose signed service configuration
-  update    Check for or install a newer CLI version
-  cli-version Show the installed CLI version
-  compile   Compile a mini program with ${brand.compilerPackageName}
-  wgt       Alias of build for compatibility
-  preview   Legacy local static preview server
-  web       Legacy H5 container command; prefer dev
-  login     Reserved provider-backed login command (unsupported by signed service)
-  debug-preview Upload a signed debug preview package and print a QR code
-  service-preview Generate signed service trial preview information
-  submit-audit Submit a signed service trial version for audit
-  version   Query signed service version information
-  audit-status Query signed service audit status
-  audit     Alias of submit-audit for provider integrations
-
-${translate(locale, 'commonOptions')}:
-  --project <path>       Mini program project path, defaults to current directory
-  --out <path>           Output directory, defaults to dist/<command>
-  --app-id <id>          Override project app id
-  --name <name>          Project name for init or metadata override
-  --entry-path <path>    Override entry path
-  --source-dir <path>    Already-produced mini app output directory for packaging
-  --compiled-dir <path>  Alias of --source-dir
-  --version-code <n>     Package version code
-  --version <version>    Package/service version
-  --version-name <name>  Package version name
-  --host <host>          Preview host
-  --port <port>          Preview port, use 0 for a random free port
-  --container-dir <path> Web container dist directory
-  --compiler-module <path> Use a local compiler module instead of ${brand.compilerPackageName}
-  --provider <module>    Provider module or "local-file" for provider commands
-  --provider-out <path>  Output directory for provider-generated records
-  --server-url <url>     Signed service base URL
-  --profile <name>       User-level service profile name
-  --key <key>            Signed service key (prefer NEUX_CLI_KEY in CI)
-  --config <path>        User-level CLI config path, defaults to ~/.neux/config.json
-  --registry <url>       npm registry for CLI self-update
-  --check                Check updates without installing
-  --dry-run              Check update/install intent without installing
-  --auto-update          Enable automatic CLI update for this run
-  --no-auto-update       Disable automatic CLI update for this run
-  --desc <text>          Upload description
-  --changelog <text>     Upload changelog, also used as description fallback
-  --channel <channel>    Service channel for preview/upload/audit
-  --page-path <path>     Debug/preview launch page path
-  --query <query>        Debug/preview launch query string
-  --scene <scene>        Debug/preview launch scene
-  --launch-from <source> Debug/preview launch source
-  --location <location>  Debug/preview launch location
-  --qr-format <format>   QR output format: png, terminal, or none
-  --qr-output <path>     Write QR output to a file
-  --copy                 Copy deeplink/QR payload to clipboard when supported
-  --proxy <url>          Proxy hint for service/provider integrations
-  --preview              Return trial preview during upload
-  --submit-audit         Submit trial version after upload
-  --auto-publish         Ask audit service to publish automatically when supported
-  --version-id <id>      Service version id
-  --version-number <v>   Service version number
-  --build                Build before pack/preview
-  --no-open              Do not open the browser automatically
-  --json                 Print machine-readable JSON
-  --lang <locale>        Output language: en or zh-CN
-  --interactive          Enable interactive prompts
-  --no-interactive       Disable interactive prompts
-  --stay                 Keep preview/web server running
-  --watch, -w            Rebuild on project file changes
-  --force                Allow init to write into a non-empty directory
-  --version, -v          Show CLI version
-  --help                 Show help
-`
-}
 
 function parse(argv) {
   const args = [...argv]
@@ -365,9 +282,13 @@ async function main() {
     return
   }
   if (!command || command === '--help' || options.help) {
-    process.stdout.write(help(locale))
+    const subcommand = command === 'config' ? options._[0] : undefined
+    process.stdout.write(command === '--help' || !command
+      ? rootHelp(locale)
+      : help(locale, command, subcommand))
     return
   }
+  warnIfDeprecated(command, locale)
   if (options.qrFormat) normalizeQrFormat(options.qrFormat)
 
   if (command !== 'update') {

package/src/core/help.js

@@ -0,0 +1,507 @@
+import { brand } from './brand.js'
+import { translate } from './i18n.js'
+
+const commandGroups = [
+  {
+    title: 'Core commands',
+    commands: [
+      ['init', 'Create a new mini program project'],
+      ['inspect', 'Inspect project metadata and diagnostics'],
+      ['dev', 'Start local development with H5 preview and live reload'],
+      ['build', 'Build a client .wgt package'],
+      ['upload', 'Upload a signed service trial package'],
+      ['debug', 'Upload a debug package and print a QR code'],
+      ['submit', 'Submit a signed service trial version for audit'],
+      ['status', 'Query signed service version information'],
+      ['config', 'Diagnose or update signed service configuration'],
+      ['update', 'Check for or install a newer CLI version'],
+    ],
+  },
+  {
+    title: 'Advanced commands',
+    commands: [
+      ['compile', 'Compile without creating a delivery package'],
+      ['pack', 'Package an existing compiled output'],
+      ['service-preview', 'Generate signed service trial preview information'],
+      ['audit-status', 'Query signed service audit status'],
+      ['cli-version', 'Show detailed CLI package information'],
+    ],
+  },
+  {
+    title: 'Compatibility aliases',
+    commands: [
+      ['wgt', 'Alias of build'],
+      ['meta', 'Alias of status'],
+      ['version', 'Alias of status'],
+      ['debug-preview', 'Compatibility spelling for debug'],
+      ['submit-audit', 'Compatibility spelling for submit'],
+      ['audit', 'Provider/service compatibility command'],
+    ],
+  },
+  {
+    title: 'Legacy commands',
+    commands: [
+      ['preview', 'Legacy local static preview server'],
+      ['web', 'Legacy H5 container command; prefer dev'],
+    ],
+  },
+]
+
+const commonHelp = `  --project <path>       Project path, defaults to current directory
+  --out <path>           Output directory; see <command> --help for defaults
+  --json                 Print machine-readable JSON
+  --lang <locale>        Output language: en or zh-CN
+  --help                 Show command help
+  --version, -v          Show CLI version`
+
+const helpTranslations = new Map([
+  ['Core commands:', '核心命令：'],
+  ['Advanced commands:', '高级命令：'],
+  ['Provider commands:', 'Provider 命令：'],
+  ['Compatibility aliases:', '兼容别名：'],
+  ['Legacy commands:', '旧版命令：'],
+  ['Create a new mini program project', '创建新的小程序项目'],
+  ['Inspect project metadata and diagnostics', '检查项目元数据和诊断信息'],
+  ['Inspect project metadata and configuration diagnostics.', '检查项目元数据和配置诊断信息。'],
+  ['Start local development with H5 preview and live reload', '启动本地开发、H5 预览和热更新'],
+  ['Start local development with the H5 container and live reload.', '启动本地开发、H5 容器和热更新。'],
+  ['Build a client .wgt package', '构建客户端 `.wgt` 交付包'],
+  ['Upload a signed service trial package', '上传 signed service 体验包'],
+  ['Upload a debug package and print a QR code', '上传调试包并输出二维码'],
+  ['Submit a signed service trial version for audit', '提交 signed service 体验版本审核'],
+  ['Query signed service version information', '查询 signed service 版本信息'],
+  ['Diagnose or update signed service configuration', '诊断或更新 signed service 配置'],
+  ['Diagnose signed service configuration', '诊断 signed service 配置'],
+  ['Check for or install a newer CLI version', '检查或安装新版 CLI'],
+  ['Provider-specific authentication', 'Provider 专属认证'],
+  ['Alias of build', 'build 的别名'],
+  ['Alias of status', 'status 的别名'],
+  ['Compatibility spelling for debug', 'debug 的兼容写法'],
+  ['Compatibility spelling for submit', 'submit 的兼容写法'],
+  ['Provider/service compatibility command', 'Provider/service 兼容命令'],
+  ['Legacy local static preview server', '旧版本地静态预览服务器'],
+  ['Legacy H5 container command; prefer dev', '旧版 H5 容器命令；建议使用 dev'],
+  ['Project path, defaults to current directory', '项目路径，默认当前目录'],
+  ['Output directory; see <command> --help for defaults', '输出目录；默认值请查看 <command> --help'],
+  ['Output language: en or zh-CN', '输出语言：en 或 zh-CN'],
+  ['Show command help', '显示命令帮助'],
+  ['Show CLI version', '显示 CLI 版本'],
+  ['Create a new mini program project.', '创建新的小程序项目。'],
+  ['Inspect project metadata and diagnostics.', '检查项目元数据和诊断信息。'],
+  ['Start local development with H5 preview and live reload.', '启动本地开发、H5 预览和热更新。'],
+  ['Build a client .wgt delivery package.', '构建客户端 `.wgt` 交付包。'],
+  ['Build and upload a signed service trial package.', '构建并上传 signed service 体验包。'],
+  ['Build and upload a signed debug preview package.', '构建并上传 signed service 调试预览包。'],
+  ['Submit a signed service trial version for audit.', '提交 signed service 体验版本审核。'],
+  ['Query signed service version information.', '查询 signed service 版本信息。'],
+  ['Diagnose or update signed service configuration', '诊断或更新 signed service 配置'],
+  ['Check for or install a newer CLI version.', '检查或安装新版 CLI。'],
+  ['Compile without creating a delivery package', '仅编译，不创建交付包'],
+  ['Compile a mini program without creating a delivery package.', '仅编译小程序，不创建交付包。'],
+  ['Package an existing compiled output', '将已有编译产物打包'],
+  ['Package an existing compiled output as a local archive.', '将已有编译产物打包为本地归档。'],
+  ['Generate signed service trial preview information.', '生成 signed service 体验预览信息。'],
+  ['Query signed service audit status.', '查询 signed service 审核状态。'],
+  ['Show detailed CLI package information.', '显示详细的 CLI 包信息。'],
+  ['Provider-specific authentication.', 'Provider 专属认证。'],
+  ['The default signed service does not implement login.', '默认 signed service 不支持 login。'],
+  ['Provider-specific authentication. The default signed service does not implement login.', 'Provider 专属认证。默认 signed service 不支持 login。'],
+  ['Create a new mini program project.', '创建新的小程序项目。'],
+  ['Alias of build', 'build 的别名'],
+  ['Alias of status', 'status 的别名'],
+  ['Compatibility spelling for debug', 'debug 的兼容写法'],
+  ['Compatibility spelling for submit', 'submit 的兼容写法'],
+  ['Provider/service compatibility command', 'Provider/service 兼容命令'],
+  ['Legacy local static preview server', '旧版本地静态预览服务器'],
+  ['Legacy H5 container command; prefer dev', '旧版 H5 容器命令；建议使用 dev'],
+  ['Usage:', '用法：'],
+  ['Options:', '选项：'],
+  ['Subcommands:', '子命令：'],
+  ['Run "neux config <subcommand> --help" for subcommand options.', '运行 "neux config <subcommand> --help" 查看子命令选项。'],
+  ['Initial app id', '初始 App ID'],
+  ['Initial project name', '初始项目名称'],
+  ['Signed service base URL', 'signed service 基础地址'],
+  ['Initial CLI key', '初始 CLI Key'],
+  ['Allow writing into a non-empty directory', '允许写入非空目录'],
+  ['Disable interactive prompts', '禁用交互式询问'],
+  ['Print machine-readable JSON', '输出机器可读 JSON'],
+  ['Project path', '项目路径'],
+  ['Mini program project path', '小程序项目路径'],
+  ['Output directory, defaults to dist/dev', '输出目录，默认是 dist/dev'],
+  ['Output directory, defaults to dist/release', '输出目录，默认是 dist/release'],
+  ['Output directory, defaults to dist/build', '输出目录，默认是 dist/build'],
+  ['Output directory, defaults to dist/pack', '输出目录，默认是 dist/pack'],
+  ['Output directory, defaults to dist/preview', '输出目录，默认是 dist/preview'],
+  ['Output directory, defaults to dist/web', '输出目录，默认是 dist/web'],
+  ['Preview host', '预览主机'],
+  ['Preview port, use 0 for a random free port', '预览端口，使用 0 随机分配空闲端口'],
+  ['Preview port', '预览端口'],
+  ['Web container dist directory', 'Web 容器 dist 目录'],
+  ['Use a local compiler module', '使用本地编译器模块'],
+  ['Do not open the browser automatically', '不要自动打开浏览器'],
+  ['Print lifecycle events as JSON Lines', '以 JSON Lines 输出生命周期事件'],
+  ['Package version name', '包版本名称'],
+  ['Package version code', '包版本 code'],
+  ['Alias of --version-name', '--version-name 的别名'],
+  ['Package an existing compiled output', '打包已有编译产物'],
+  ['Alias of --source-dir', '--source-dir 的别名'],
+  ['Override project app id', '覆盖项目 App ID'],
+  ['User-level service profile name', '用户级服务 profile 名称'],
+  ['Signed service key', 'signed service Key'],
+  ['Return trial preview information', '返回体验预览信息'],
+  ['Submit the trial version after upload', '上传后提交体验版本审核'],
+  ['Upload changelog', '上传变更说明'],
+  ['Service channel', '服务通道'],
+  ['Provider module or "local-file"', 'Provider 模块或 "local-file"'],
+  ['Build before upload', '上传前先构建'],
+  ['Launch page path', '启动页面路径'],
+  ['Launch query string', '启动 query 字符串'],
+  ['Launch scene', '启动场景'],
+  ['Launch source', '启动来源'],
+  ['Launch location', '启动位置'],
+  ['QR output: png, terminal, or none', '二维码输出格式：png、terminal 或 none'],
+  ['Write QR output to a file', '将二维码输出到文件'],
+  ['Copy the deeplink when supported', '在支持时复制 deeplink'],
+  ['Service version id', '服务版本 ID'],
+  ['Service version number', '服务版本号'],
+  ['Ask the audit service to publish automatically', '请求审核服务自动发布'],
+  ['Provider module', 'Provider 模块'],
+  ['Save the current project\'s CLI key in the user-level CLI config.', '将当前项目的 CLI Key 保存到用户级 CLI 配置。'],
+  ['User-level CLI config path', '用户级 CLI 配置路径'],
+  ['Diagnose signed service configuration without exposing key values.', '诊断 signed service 配置，不暴露 Key 内容。'],
+  ['Check updates without installing', '只检查更新，不安装'],
+  ['Check update/install intent without installing', '检查更新/安装意图，不安装'],
+  ['npm registry for the update', '更新使用的 npm registry'],
+  ['npm executable to use', '使用的 npm 可执行文件'],
+  ['Compatibility alias: use "neux build" instead.', '兼容别名：请改用 "neux build"。'],
+  ['Compatibility alias: use "neux status" instead.', '兼容别名：请改用 "neux status"。'],
+  ['Compatibility alias: use "neux debug" instead.', '兼容别名：请改用 "neux debug"。'],
+  ['Compatibility alias: use "neux submit" instead.', '兼容别名：请改用 "neux submit"。'],
+  ['Provider/service compatibility command. Use "neux submit" for the signed service.', 'Provider/service 兼容命令。signed service 请使用 "neux submit"。'],
+  ['Legacy local static preview server. Prefer "neux dev".', '旧版本地静态预览服务器。建议使用 "neux dev"。'],
+  ['Legacy H5 container command. Prefer "neux dev".', '旧版 H5 容器命令。建议使用 "neux dev"。'],
+  ['This command is legacy; use `neux dev` for the local H5 workflow.', '该命令已是旧版入口；本地 H5 工作流请使用 `neux dev`。'],
+  ['This command is legacy; use `neux dev` instead.', '该命令已是旧版入口；请使用 `neux dev`。'],
+  ['Common options:', '通用选项：'],
+  ['通用选项:', '通用选项：'],
+  ['Generate signed service trial preview information', '生成 signed service 体验预览信息'],
+  ['Query signed service audit status', '查询 signed service 审核状态'],
+  ['Show detailed CLI package information', '显示详细的 CLI 包信息'],
+  ['Save the current project\'s CLI key', '保存当前项目的 CLI Key'],
+  ['Run "neux <command> --help" for command-specific options.', '运行 "neux <command> --help" 查看命令级选项。'],
+])
+
+function localizeHelpText(locale, text) {
+  if (String(locale).toLowerCase() !== 'zh-cn') return text
+  let localized = text
+  const translations = [...helpTranslations].sort(([left], [right]) => right.length - left.length)
+  for (const [source, target] of translations) localized = localized.replaceAll(source, target)
+  return localized
+}
+
+const commandHelp = {
+  init: `Usage: ${brand.commandName} init <dir> [options]
+
+Create a new mini program project.
+
+Options:
+  --app-id <id>          Initial app id
+  --name <name>          Initial project name
+  --server-url <url>     Signed service base URL
+  --key <key>            Initial CLI key
+  --force                Allow writing into a non-empty directory
+  --no-interactive       Disable interactive prompts
+  --json                 Print machine-readable JSON`,
+  inspect: `Usage: ${brand.commandName} inspect [options]
+
+Inspect project metadata and configuration diagnostics.
+
+Options:
+  --project <path>       Project path
+  --json                 Print machine-readable JSON`,
+  dev: `Usage: ${brand.commandName} dev [options]
+
+Start local development with the H5 container and live reload.
+
+Options:
+  --project <path>       Mini program project path
+  --out <path>           Output directory, defaults to dist/dev
+  --host <host>          Preview host
+  --port <port>          Preview port, use 0 for a random free port
+  --container-dir <path> Web container dist directory
+  --compiler-module <path> Use a local compiler module
+  --no-open              Do not open the browser automatically
+  --json                 Print lifecycle events as JSON Lines`,
+  build: `Usage: ${brand.commandName} build [options]
+
+Build a client .wgt delivery package.
+
+Options:
+  --project <path>       Mini program project path
+  --out <path>           Output directory, defaults to dist/release
+  --version-name <name>  Package version name
+  --version-code <n>     Package version code
+  --version <version>    Alias of --version-name
+  --source-dir <path>    Package an existing compiled output
+  --compiled-dir <path>  Alias of --source-dir
+  --compiler-module <path> Use a local compiler module
+  --json                 Print machine-readable JSON`,
+  upload: `Usage: ${brand.commandName} upload [options]
+
+Build and upload a signed service trial package.
+
+Options:
+  --project <path>       Mini program project path
+  --out <path>           Output directory, defaults to dist/release
+  --server-url <url>     Signed service base URL
+  --app-id <id>          Override project app id
+  --profile <name>       User-level service profile name
+  --key <key>            Signed service key
+  --version-name <name>  Package version name
+  --version-code <n>     Package version code
+  --preview              Return trial preview information
+  --submit-audit         Submit the trial version after upload
+  --changelog <text>     Upload changelog
+  --channel <channel>    Service channel
+  --provider <module>    Provider module or "local-file"
+  --build                Build before upload
+  --json                 Print machine-readable JSON`,
+  debug: `Usage: ${brand.commandName} debug [options]
+
+Build and upload a signed debug preview package.
+
+Options:
+  --project <path>       Mini program project path
+  --server-url <url>     Signed service base URL
+  --app-id <id>          Override project app id
+  --profile <name>       User-level service profile name
+  --key <key>            Signed service key
+  --page-path <path>     Launch page path
+  --query <query>        Launch query string
+  --scene <scene>        Launch scene
+  --launch-from <source> Launch source
+  --location <location>  Launch location
+  --qr-format <format>   QR output: png, terminal, or none
+  --qr-output <path>     Write QR output to a file
+  --copy                 Copy the deeplink when supported
+  --json                 Print machine-readable JSON`,
+  submit: `Usage: ${brand.commandName} submit [options]
+
+Submit a signed service trial version for audit.
+
+Options:
+  --server-url <url>     Signed service base URL
+  --app-id <id>          Override project app id
+  --profile <name>       User-level service profile name
+  --key <key>            Signed service key
+  --version-id <id>      Service version id
+  --version-number <v>   Service version number
+  --channel <channel>    Service channel
+  --auto-publish         Ask the audit service to publish automatically
+  --provider <module>    Provider module
+  --json                 Print machine-readable JSON`,
+  status: `Usage: ${brand.commandName} status [options]
+
+Query signed service version information.
+
+Options:
+  --server-url <url>     Signed service base URL
+  --app-id <id>          Override project app id
+  --profile <name>       User-level service profile name
+  --key <key>            Signed service key
+  --provider <module>    Provider module
+  --json                 Print machine-readable JSON`,
+  config: `Usage: ${brand.commandName} config <subcommand> [options]
+
+Subcommands:
+  doctor                 Diagnose signed service configuration
+  set                    Save the current project's CLI key
+
+Run "${brand.commandName} config <subcommand> --help" for subcommand options.`,
+  'config set': `Usage: ${brand.commandName} config set [options]
+
+Save the current project's CLI key in the user-level CLI config.
+
+Options:
+  --project <path>       Mini program project path
+  --app-id <id>          Override project app id
+  --key <key>            CLI key
+  --config <path>        User-level CLI config path
+  --no-interactive       Disable interactive prompts
+  --json                 Print machine-readable JSON`,
+  'config doctor': `Usage: ${brand.commandName} config doctor [options]
+
+Diagnose signed service configuration without exposing key values.
+
+Options:
+  --project <path>       Mini program project path
+  --server-url <url>     Signed service base URL
+  --app-id <id>          Override project app id
+  --profile <name>       User-level service profile name
+  --key <key>            Signed service key
+  --config <path>        User-level CLI config path
+  --json                 Print machine-readable JSON`,
+  update: `Usage: ${brand.commandName} update [check] [options]
+
+Check for or install a newer CLI version.
+
+Options:
+  --check                Check updates without installing
+  --dry-run              Check update/install intent without installing
+  --registry <url>       npm registry for the update
+  --npm <command>        npm executable to use
+  --json                 Print machine-readable JSON`,
+  compile: `Usage: ${brand.commandName} compile [options]
+
+Compile a mini program without creating a delivery package.
+
+Options:
+  --project <path>       Mini program project path
+  --out <path>           Output directory, defaults to dist/build
+  --compiler-module <path> Use a local compiler module
+  --watch, -w            Rebuild on project file changes
+  --json                 Print machine-readable JSON`,
+  pack: `Usage: ${brand.commandName} pack [options]
+
+Package an existing compiled output as a local archive.
+
+Options:
+  --project <path>       Mini program project path
+  --out <path>           Output directory, defaults to dist/pack
+  --source-dir <path>    Already-produced mini app output directory
+  --compiled-dir <path>  Alias of --source-dir
+  --version-name <name>  Package version name
+  --version-code <n>     Package version code
+  --json                 Print machine-readable JSON`,
+  'service-preview': `Usage: ${brand.commandName} service-preview [options]
+
+Generate signed service trial preview information.
+
+Options:
+  --server-url <url>     Signed service base URL
+  --app-id <id>          Override project app id
+  --profile <name>       User-level service profile name
+  --key <key>            Signed service key
+  --version-id <id>      Service version id
+  --version-number <v>   Service version number
+  --provider <module>    Provider module
+  --json                 Print machine-readable JSON`,
+  'audit-status': `Usage: ${brand.commandName} audit-status [options]
+
+Query signed service audit status.
+
+Options:
+  --server-url <url>     Signed service base URL
+  --app-id <id>          Override project app id
+  --profile <name>       User-level service profile name
+  --key <key>            Signed service key
+  --version-id <id>      Service version id
+  --provider <module>    Provider module
+  --json                 Print machine-readable JSON`,
+  'cli-version': `Usage: ${brand.commandName} cli-version [options]
+
+Show detailed CLI package information.
+
+Options:
+  --json                 Print machine-readable JSON`,
+}
+
+for (const [alias, target] of Object.entries({
+  wgt: 'build',
+  meta: 'status',
+  version: 'status',
+  'debug-preview': 'debug',
+  'submit-audit': 'submit',
+})) {
+  commandHelp[alias] = `${commandHelp[target]}\n\nCompatibility alias: use "${brand.commandName} ${target}" instead.`
+}
+
+commandHelp.audit = `Usage: ${brand.commandName} audit [options]
+
+Provider/service compatibility command. Use "${brand.commandName} submit" for the signed service.
+
+Options:
+  --provider <module>    Provider module
+  --version-id <id>      Service version id
+  --version-number <v>  Service version number
+  --json                 Print machine-readable JSON`
+
+commandHelp.preview = `Usage: ${brand.commandName} preview [options]
+
+Legacy local static preview server. Prefer "${brand.commandName} dev".
+
+Options:
+  --project <path>       Mini program project path
+  --out <path>           Output directory, defaults to dist/preview
+  --host <host>          Preview host
+  --port <port>          Preview port
+  --stay                 Keep the preview server running
+  --json                 Print machine-readable JSON`
+
+commandHelp.web = `Usage: ${brand.commandName} web [options]
+
+Legacy H5 container command. Prefer "${brand.commandName} dev".
+
+Options:
+  --project <path>       Mini program project path
+  --out <path>           Output directory, defaults to dist/web
+  --host <host>          Preview host
+  --port <port>          Preview port
+  --watch, -w            Rebuild on project file changes
+  --no-open              Do not open the browser automatically
+  --json                 Print lifecycle events as JSON Lines`
+
+commandHelp.login = `Usage: ${brand.commandName} login [options]
+
+Provider-specific authentication. The default signed service does not implement login.
+
+Options:
+  --provider <module>    Provider module
+  --project <path>       Mini program project path
+  --json                 Print machine-readable JSON`
+
+const deprecatedCommands = {
+  wgt: 'Use `neux build` instead.',
+  meta: 'Use `neux status` instead.',
+  version: 'Use `neux status` instead.',
+  'debug-preview': 'Use `neux debug` instead.',
+  'submit-audit': 'Use `neux submit` instead.',
+  audit: 'Use `neux submit` for the signed service.',
+  preview: 'This command is legacy; use `neux dev` for the local H5 workflow.',
+  web: 'This command is legacy; use `neux dev` instead.',
+}
+
+function formatCommandGroup(group) {
+  const width = Math.max(...group.commands.map(([name]) => name.length))
+  return `${group.title}:\n${group.commands
+    .map(([name, description]) => `  ${name.padEnd(width + 2)}${description}`)
+    .join('\n')}`
+}
+
+export function rootHelp(locale = 'en') {
+  const content = `${translate(locale, 'usage')}: ${brand.commandName} <command> [options]
+
+${commandGroups.map(formatCommandGroup).join('\n\n')}
+
+${translate(locale, 'commonOptions')}:
+${commonHelp}
+
+Run "${brand.commandName} <command> --help" for command-specific options.
+`
+  return localizeHelpText(locale, content)
+}
+
+export function help(locale = 'en', command, subcommand) {
+  const target = subcommand ? `${command} ${subcommand}` : command
+  const output = commandHelp[target] || commandHelp[command] || rootHelp(locale)
+  if (!commandHelp[target] && !commandHelp[command]) return output
+  const localized = localizeHelpText(locale, output)
+  return localized.endsWith('\n') ? localized : `${localized}\n`
+}
+
+export function warnIfDeprecated(command, locale = 'en') {
+  const message = deprecatedCommands[command]
+  if (!message) return
+  const warning = localizeHelpText(locale, `Warning: \`${brand.commandName} ${command}\` is deprecated. ${message}\n`)
+  process.stderr.write(warning)
+}

package/src/core/web.js

@@ -192,6 +192,10 @@ export function liveReloadScript() {
   return `<script>
 (() => {
   const source = new EventSource('/__dimina_live_reload');
+  let hotUpdateQueue = Promise.resolve();
+  let hotUpdateRecoveryTimer = null;
+  let hotUpdateRecoveryActive = false;
+  let reloadRequested = false;
   const refreshStylesheets = (doc, timestamp) => {
     if (!doc) return;
     for (const link of doc.querySelectorAll('link[rel="stylesheet"][href]')) {
@@ -209,36 +213,66 @@ export function liveReloadScript() {
       } catch {}
     }
   };
+  const requestReload = () => {
+    if (reloadRequested) return;
+    reloadRequested = true;
+    window.location.reload();
+  };
+  const armHotUpdateRecovery = () => {
+    hotUpdateRecoveryActive = true;
+    clearTimeout(hotUpdateRecoveryTimer);
+    hotUpdateRecoveryTimer = setTimeout(() => {
+      hotUpdateRecoveryActive = false;
+    }, 2000);
+  };
+  const isDomPatchError = (value) => {
+    const message = value?.message || value?.reason?.message || value?.reason || value;
+    return /(?:insertBefore|appendChild|removeChild|parentNode)/.test(String(message || ''));
+  };
+  const recoverFromAsyncHotUpdateError = (event) => {
+    if (hotUpdateRecoveryActive && isDomPatchError(event?.error || event)) {
+      requestReload();
+    }
+  };
+  window.addEventListener('error', recoverFromAsyncHotUpdateError);
+  window.addEventListener('unhandledrejection', recoverFromAsyncHotUpdateError);
   const applyHotUpdate = (handler, payload) => {
+    armHotUpdateRecovery();
     try {
       if (typeof handler !== 'function') {
-        window.location.reload();
+        requestReload();
         return;
       }
       const result = handler(payload);
       if (result && typeof result.then === 'function') {
-        result.then((handled) => {
-          if (handled === false || handled == null) window.location.reload();
-        }).catch(() => window.location.reload());
-        return;
+        return result.then((handled) => {
+          if (handled === false || handled == null) requestReload();
+        }).catch(() => requestReload());
       }
       if (result === false || result == null) {
-        window.location.reload();
+        requestReload();
       }
+      return result;
     } catch {
-      window.location.reload();
+      requestReload();
     }
   };
+  const enqueueHotUpdate = (handler, payload) => {
+    hotUpdateQueue = hotUpdateQueue
+      .then(() => applyHotUpdate(handler, payload))
+      .catch(() => requestReload());
+    return hotUpdateQueue;
+  };
   source.addEventListener('style-update', refreshAllStylesheets);
   source.addEventListener('view-update', (event) => {
     const payload = JSON.parse(event.data || '{}');
-    applyHotUpdate(window.__diminaHotUpdateView, payload);
+    enqueueHotUpdate(window.__diminaHotUpdateView, payload);
   });
   source.addEventListener('logic-update', (event) => {
     const payload = JSON.parse(event.data || '{}');
-    applyHotUpdate(window.__diminaHotUpdateLogic, payload);
+    enqueueHotUpdate(window.__diminaHotUpdateLogic, payload);
   });
-  source.addEventListener('reload', () => location.reload());
+  source.addEventListener('reload', requestReload);
 })();
 </script>`
 }