@neuxnet/neux-cli 0.2.3

package/README.md

@@ -0,0 +1,438 @@
+# Neux CLI
+
+[中文文档](./README.zh-CN.md)
+
+Standalone Neux automation package for local development, CI/CD, and future IDE Node-side integration.
+
+## Installation
+
+Neux CLI is published publicly under the `@neuxnet` npm scope. If your npm
+configuration maps this scope to a private registry, override it explicitly:
+
+Install the CLI globally:
+
+```sh
+npm install -g @neuxnet/neux-cli --registry=https://registry.npmjs.org/
+neux --version
+neux --help
+```
+
+Upgrade to the latest public version:
+
+```sh
+npm install -g @neuxnet/neux-cli@latest --registry=https://registry.npmjs.org/
+```
+
+If a private `@neuxnet:registry` setting still takes precedence, remove that
+setting for the install or use a separate npm user config containing
+`registry=https://registry.npmjs.org/`.
+
+## Commands
+
+```sh
+neux init ./miniapp --app-id touristappid --name "My Miniapp"
+neux --version
+neux cli-version --json
+neux inspect --project ./miniapp --json
+neux dev --project ./miniapp --port 7788
+neux build --project ./miniapp --version 1.0.1 --json
+neux config doctor --project ./miniapp --server-url https://miniapp.example.com --json
+neux update --check --json
+neux update --registry https://registry.example.com
+NEUX_CLI_KEY_APP_XXX=key_xxx neux upload --project ./miniapp --app-id app_xxx --server-url https://miniapp.example.com --preview --json
+NEUX_CLI_KEY_APP_XXX=key_xxx neux debug --project ./miniapp --app-id app_xxx --server-url https://miniapp.example.com
+NEUX_CLI_KEY_APP_XXX=key_xxx neux debug --project ./miniapp --app-id app_xxx --server-url https://miniapp.example.com --page-path pages/index/index --query foo=bar --qr-output ./dist/release/preview.qr.txt
+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.
+
+When the command runs inside a mini program project, `--project` defaults to the current directory. Output directories also have command-level defaults:
+
+| Command | Default output |
+| --- | --- |
+| `neux build` | `dist/release` |
+| `neux compile` | `dist/build` |
+| `neux dev` | `dist/dev` |
+| `neux web` | `dist/web` |
+| `neux pack` | `dist/pack` |
+| `neux wgt` | `dist/release` |
+| `neux preview` | `dist/preview` |
+
+## Updating The CLI
+
+Check for a newer CLI without installing it:
+
+```sh
+neux update --check
+```
+
+Install the latest version from the configured npm registry:
+
+```sh
+neux update
+```
+
+When `--registry` is omitted, `neux update` first reads the package scope registry from the current npm config such as `@neuxnet:registry`, then falls back to the default `registry`.
+
+Use a private registry:
+
+```sh
+neux update --registry https://registry.example.com
+```
+
+Automatic update is opt-in:
+
+```sh
+NEUX_CLI_AUTO_UPDATE=1 neux dev
+```
+
+Automatic update failures are printed as warnings and do not stop the original command. In CI/CD, prefer `neux update --check --json` or a pinned CLI version when deterministic toolchains matter.
+
+## Mini Program Scripts
+
+Create a new project:
+
+```sh
+npx @neuxnet/neux-cli init my-miniapp --app-id touristappid --name "My Miniapp"
+cd my-miniapp
+```
+
+Mini program projects can keep their own npm scripts and call the CLI from the project root:
+
+```json
+{
+  "scripts": {
+    "build": "neux build",
+    "dev": "neux dev",
+    "upload": "neux upload --preview",
+    "debug": "neux debug",
+    "submit": "neux submit"
+  }
+}
+```
+
+The generated project declares the CLI as a local `devDependency` intentionally. The
+`npm run` commands then resolve `neux` from `node_modules/.bin`, so the project,
+other developers, and CI use the project's declared CLI version range instead of
+depending on an untracked global installation. Commit the generated lockfile to
+pin the exact version. `neux init` fills this value from the installed CLI package;
+it does not hard-code an old release. If the project is only operated with a
+globally installed CLI, this dependency is not technically required, but the
+scripts become dependent on each machine's global version and are no longer
+reproducible.
+
+`npm run build` compiles the mini app and writes the client `.wgt` package under `dist/release/`. `npm run dev` starts the browser H5 container, watches project files, reloads after successful rebuilds, and exposes a same-origin `/proxy` endpoint for browser network requests. Individual mini programs do not need to maintain proxy scripts. The proxy is development-only and is not included in `.wgt` packages or native runtime behavior. `npm run upload` uploads a trial package, `npm run debug` uploads a debug preview package and prints a scannable terminal QR code, and `npm run submit` submits a trial version for audit.
+
+The proxy request body follows the browser network adapter shape:
+
+```json
+{
+  "url": "https://api.example.com/path",
+  "method": "POST",
+  "data": {},
+  "header": {}
+}
+```
+
+Only loopback browser origins are allowed by default. Private, loopback, and reserved
+target addresses are rejected. Set `DIMINA_PROXY_ALLOWED_ORIGINS` to a comma-separated
+allowlist when an additional development origin is required.
+
+Debug and upload commands accept optional service metadata and launch parameters:
+
+```sh
+neux debug --page-path pages/detail/index --query 'id=1' --scene 1001 --launch-from cli --location 31.2,121.5
+neux debug --qr-format png --qr-output ./dist/release/preview.png
+neux debug --qr-format terminal
+neux debug --qr-format none --qr-output ./dist/release/preview.qr.txt
+neux upload --preview --changelog "Release notes" --channel test
+neux submit --version-id 123 --channel test --auto-publish
+```
+
+Text-mode `debug` / `debug-preview` prints a terminal QR code by default. The renderer uses compact ANSI upper-half cells with explicit colors for both module rows and a four-module quiet zone. Encoding two vertical modules in each terminal cell keeps the QR code close to square while avoiding reliance on the terminal's default foreground/background colors, improving scanning in Mac Terminal and Android Studio Terminal. Use `--qr-format png --qr-output <path>` for an image, `--qr-format none --qr-output <path>` to archive the raw payload, and `--copy` to copy the deeplink. `--json` keeps stdout machine-readable and does not print a QR code.
+
+For tooling that needs the old compiler-only behavior, use `neux compile`. The `neux wgt` command remains as a compatibility alias for the delivery build.
+
+When running this repository directly before publishing/installing the CLI package, use yalc so package name and bin command stay consistent with the published shape:
+
+```sh
+cd neux-cli
+yalc publish
+
+cd ../fe/example/base
+yalc add @neuxnet/neux-cli
+npm install
+npm run build
+```
+
+## Node API
+
+```js
+import {
+  buildProject,
+  createProjectWatcher,
+  createLocalFileProvider,
+  createUploadProvider,
+  initProject,
+  inspectProject,
+  packProject,
+  updateCli,
+  startDev,
+  startPreview,
+  startWeb,
+} from '@neuxnet/neux-cli'
+
+await initProject({ _: ['./miniapp'], appId: 'touristappid', name: 'My Miniapp' })
+await updateCli({ check: true })
+const info = await inspectProject({ project: './miniapp' })
+const build = await buildProject({
+  project: './miniapp',
+  captureLogs: true,
+  onLog(log) {
+    console.log(`[${log.level}] ${log.message}`)
+  },
+})
+const pack = await packProject({ project: './miniapp', out: './artifacts' })
+const session = await startPreview({ project: './miniapp', host: '127.0.0.1', port: 0 })
+await session.close()
+
+const web = await startWeb({ project: './miniapp', port: 0, open: false })
+console.log(web.url)
+await web.close()
+
+const dev = await startDev({ project: './miniapp', port: 0, open: false })
+console.log(dev.url)
+await dev.close()
+
+const watcher = await createProjectWatcher({
+  project: './miniapp',
+  onChange: () => buildProject({ project: './miniapp', out: './dist' }),
+})
+watcher.close()
+
+const provider = createUploadProvider()
+await provider.upload('./artifacts/app.zip') // throws DIMINA_PROVIDER_UNSUPPORTED until an adapter is supplied
+
+const localProvider = createLocalFileProvider({ providerOut: './provider-records' })
+await localProvider.login({
+  project: { projectPath: info.projectPath, appId: info.appId },
+  options: { account: 'demo' },
+})
+await localProvider.upload({
+  artifact: pack,
+  project: { projectPath: info.projectPath, appId: info.appId },
+  options: { versionCode: 1, versionName: '1.0.0' },
+})
+```
+
+The CLI is a thin adapter over these APIs so a future IDE can reuse the same lifecycle without parsing terminal output.
+
+`initProject({ _: ['./miniapp'], appId: 'touristappid', name: 'My Miniapp' })` creates the same starter project that `neux init` writes from the command line. Existing non-empty directories are rejected unless `force: true` is passed.
+
+`buildProject()` supports projects whose `project.config.json` declares `miniprogramRoot`. In that case it prepares a normalized compiler input directory beside the output directory and returns `sourceRoot`, `compilerInputPath`, and `compilerInputCreated` for IDE diagnostics. Use `captureLogs` / `onLog` for IDE status panes; keep captured builds serial within a single Node process because compiler stdout/stderr are process-global streams.
+
+`startWeb({ watch: true })` serves the bundled H5 container, rebuilds on project file changes, and sends a browser live-reload event after each successful rebuild. `startDev()` is the same development loop exposed as the stable IDE-friendly entrypoint.
+
+Long-running Node APIs accept `onEvent(event)` so IDEs can consume one stable lifecycle stream without parsing terminal output. Event names are stable: `build-start`, `build-success`, `build-error`, `ready`, `reload`, and `close`. Events are JSON-safe and omit functions from session payloads.
+
+## Signed Service Uploads
+
+The signed service API authenticates machine requests with `appId + key`. Requests send `X-App-Id`, `X-Timestamp`, `X-Nonce`, and `X-Signature`; there is no `keyId` or CLI scope field in the V2 contract.
+
+Config resolution order:
+
+1. CLI flags, such as `--server-url`, `--app-id`, `--key`, and `--profile`.
+2. Environment variables: `NEUX_CLI_SERVER_URL`, `NEUX_CLI_APP_ID`, `NEUX_CLI_PROFILE`, app/profile-specific key variables, and `NEUX_CLI_KEY`.
+3. Project config for non-key values: `neux.config.json` or top-level fields in `project.config.json`.
+4. User profiles from `$NEUX_CLI_CONFIG` or `~/.neux/config.json`.
+
+Project config example:
+
+```json
+{
+  "appId": "app_xxx",
+  "profile": "demo-private",
+  "versionName": "1.2.3",
+  "versionCode": 12
+}
+```
+
+You can also keep package metadata inside `project.config.json`:
+
+```json
+{
+  "appid": "app_xxx",
+  "compileType": "miniprogram",
+  "miniprogramRoot": "",
+  "neuxCli": {
+    "serverUrl": "https://demo-c.paas.superapp.neuvision.cn"
+  },
+  "versionName": "1.2.3",
+  "versionCode": 12,
+  "setting": {
+    "urlCheck": true,
+    "es6": true,
+    "postcss": true,
+    "minified": true
+  },
+  "packOptions": {
+    "ignore": [],
+    "include": []
+  }
+}
+```
+
+`serverUrl` can also be placed at the top level of `project.config.json`; the generated starter uses `neuxCli.serverUrl` so service settings stay separate from IDE project fields. `project.private.config.json` can override non-key local values from `project.config.json`, including `appid`, `projectname`, `versionName`, `versionCode`, `setting`, `packOptions`, and `neuxCli.serverUrl`. Keep `key` out of both files; use environment variables or `--key`.
+
+`neux build` and service upload commands use version values in this order: CLI flags (`--version-name`, `--version`, `--version-code`), `neux.config.json`, top-level `project.config.json` fields (`versionName`, `versionCode`), `package.json` `version` for `versionName`, and finally the defaults `1.0.0` / `1`.
+
+User profile example:
+
+```json
+{
+  "profiles": {
+    "demo-private": {
+      "serverUrl": "https://miniapp.example.com"
+    }
+  }
+}
+```
+
+CLI Keys are stored per App ID in the user-level `~/.neux/config.json` `keys` object, never in project config or Git. Use `neux config set` to update a key. For CI, pass the key through `--key` or environment variables.
+
+Key resolution order:
+
+1. `--key`
+2. `NEUX_CLI_KEY_<APPID_NORMALIZED>`
+3. `NEUX_CLI_KEY_<PROFILE_NORMALIZED>`
+4. `NEUX_CLI_KEY`
+5. The current App ID's key in the user-level `~/.neux/config.json`
+
+The normalized suffix is uppercased and non-alphanumeric characters become `_`. For example, app id `wxbaf4b47de04f1d8a` uses:
+
+```sh
+export NEUX_CLI_KEY_WXBAF4B47DE04F1D8A=key_xxx
+npm run upload
+```
+
+A profile named `demo-private` uses:
+
+```sh
+export NEUX_CLI_KEY_DEMO_PRIVATE=key_xxx
+npm run upload
+```
+
+For CI/CD with multiple mini apps, inject the app-specific key for each job and keep package scripts short:
+
+```yaml
+env:
+  NEUX_CLI_SERVER_URL: https://miniapp.example.com
+  NEUX_CLI_KEY_WXBAF4B47DE04F1D8A: ${{ env.MINIAPP_BASE_KEY }}
+
+steps:
+  - run: npm run upload
+```
+
+When configuration is missing, non-JSON CLI output prints the exact environment variable names that match the current project app id and profile. JSON mode returns the same suggestions in `details.suggestions`.
+
+`neux build`, `neux wgt`, and service uploads create client `.wgt` files with the same shape as the downloaded runtime package. The outer `.wgt` is a zip containing exactly `config.json` and `<appId>.zip`; the inner `<appId>.zip` contains the files from the resolved mini app production/build output directory. They do not zip the whole source project folder. Local `pack` and local `preview` keep their existing legacy `.zip` behavior.
+
+The existing `preview` command remains the legacy local static preview server. Use `service-preview` for the signed API endpoint that generates trial preview information. Trial preview and debug preview results include `qrPayload` / `deepLink` fields for CLI-side QR generation; the CLI does not call the server PNG QR endpoint. For `upload --preview`, the CLI appends the packaged `versionName` as the deeplink `version` query parameter even when the service `scanUrl` only contains `appId` and `appVerType`. In text mode, successful `debug` / `debug-preview` prints the compact ANSI half-cell terminal QR by default; `--qr-format png` generates a PNG and `--qr-format none` suppresses visual output. In `--json` mode, stdout stays machine-readable JSON and the QR payload remains available as `qrPayload`. `--qr-output <path>` selects an explicit QR output path.
+
+Use `neux config doctor` to inspect signed service configuration without exposing keys:
+
+```sh
+neux config doctor --project ./miniapp --json
+```
+
+The diagnostic output includes resolved non-key values, config source paths, missing fields, candidate key environment variables, and whether a key is present. It never prints the key value.
+
+## JSON Output Contract
+
+One-shot commands write one JSON object to stdout when `--json` is passed:
+
+```sh
+neux build --project ./miniapp --json
+```
+
+Long-running development commands write newline-delimited JSON events:
+
+```sh
+neux dev --project ./miniapp --json
+neux preview --project ./miniapp --json --stay
+```
+
+Event names are stable: `build-start`, `build-success`, `build-error`, `ready`, `reload`, and `close`. Compiler progress logs are redirected to stderr in JSON mode so stdout remains machine-readable for CI and IDE integrations.
+
+## Provider Adapters
+
+Provider commands first create a package artifact, then call the selected provider:
+
+```sh
+neux login --project ./miniapp --provider ./provider.mjs --json
+neux upload --project ./miniapp --provider ./provider.mjs --json
+neux audit --project ./miniapp --provider ./provider.mjs --json
+neux submit --project ./miniapp --provider ./provider.mjs --json
+```
+
+A provider module can export `createProvider(options)`, a default provider object, or a named `provider` object:
+
+```js
+export function createProvider(options) {
+  return {
+    async login({ project }) {
+      return { ok: true, provider: 'example', appId: project?.appId }
+    },
+    async upload({ artifact, project }) {
+      return { ok: true, provider: 'example', appId: project.appId, packagePath: artifact.packagePath }
+    },
+    async audit({ artifact }) {
+      return { ok: true, provider: 'example', manifestPath: artifact.manifestPath }
+    },
+  }
+}
+```
+
+Use `--provider local-file` for CI smoke tests. It writes local JSON records and does not contact any remote service.
+
+## Bundled Compiler
+
+The published CLI bundles the mini program compiler, so mini program projects do not need to install a separate compiler package. To refresh the bundled compiler from this repository before publishing the CLI, build the compiler package and sync the compiled output:
+
+```sh
+pnpm --dir ../fe build
+npm run sync:compiler
+```
+
+For a one-step local publish preparation flow, run:
+
+```sh
+npm run prepare:publish
+```
+
+Use `--compiler-module <path>` or `DIMINA_COMPILER_MODULE=<path>` only when testing a custom compiler module.
+
+## Web Container Asset
+
+`neux web` first looks for the bundled H5 container under `assets/container`. Refresh that asset from this repository with:
+
+```sh
+npm run sync:container
+```
+
+Use `--container-dir <path>` or `DIMINA_WEB_CONTAINER_DIR=<path>` to test a different container build.
+### Language
+
+The CLI defaults to English. Use `--lang zh-CN` or `NEUX_CLI_LANG=zh-CN` to translate CLI help and terminal result labels:
+
+```bash
+neux --help --lang zh-CN
+NEUX_CLI_LANG=zh-CN neux init ./miniapp
+```
+
+The Web container also defaults to English. Start it with `neux dev --lang zh-CN`, or add `?lang=zh-CN` to the Web URL. `--json` output keeps stable machine-readable fields regardless of the selected language.