@guanjinke/artifact-client 1.14.0 → 1.14.1

package/README.md

@@ -1,219 +1,222 @@
-# @guanjinke/artifact-client
-
-Upload, browse and download build artifacts on **Azure Blob Storage** and **Aliyun OSS**, and build and manage local **Wyn environments** from those artifacts.
-
-Requires Node.js >= 20. `az` commands talk to Azure, `oss` commands to Aliyun OSS; below they are interchangeable unless noted.
-
-## Install
-
-```bash
-npm install -g @guanjinke/artifact-client
-afm --version
-```
-
-## Credentials
-
-```bash
-afm az login  --sasurl "https://<account>.blob.core.windows.net/<container>?<SAS>"
-afm oss login --keyid <id> --key <secret> --bucket <bucket> [--region oss-cn-hangzhou]
-
-# or pass them inline on any command: --sasurl, --keyid/--key/--bucket/--region
-afm az list-plugins --sasurl "https://..."
-
-afm az config show     # print the saved credentials
-afm az config clear    # remove them
-```
-
-Saved settings live in `~/.afm/config.json`; set `AFM_CONFIG_DIR` to use another directory.
-
-## Browse artifacts
-
-```bash
-afm az list-plugins [--size]
-afm az list-majors <plugin> [--size] [--sort asc|desc]
-afm az get-latest <plugin> <major> [--size] [--no-verify]
-afm az list-minors <plugin> <major> [--size] [--sort asc|desc]
-afm az list-artifacts <plugin> <version> [--size]
-```
-
-A **major** (`9.1`, `9.0`, `9.1-hotfix1`, `9.1-oem`, `dev`, ...) is a product label, not an artifact version. Each major owns a version file (`version9.1.txt`, `versiondev.txt`) that records the version it currently points at; `get-latest` reads it and warns on stderr when that version no longer holds artifacts (`--no-verify` skips the check).
-
-## Upload
-
-```bash
-# Write the file into the version directory (major pointers untouched)
-afm az upload <plugin> <version> <artifact-name> <local-file>
-
-# ... and record it as the latest of a major in the same step
-afm az upload <plugin> <version> <artifact-name> <local-file> --set-latest --major 9.1
-
-# Or move a major separately
-afm az set-latest <plugin> <major> <version> [--no-verify]
-```
-
-Uploading and moving a major are deliberately separate: a hotfix upload cannot accidentally move `version9.1.txt`.
-
-## Download
-
-```bash
-afm az download --path "<full/storage/path>"                     [--out ./dir]
-afm az download --plugin <plugin> --ver <version> --file <name>   [--out ./dir]
-afm az download --plugin <plugin> --ver <version> --all           [--out ./dir]
-afm az download --plugin <plugin> --major <major> [--file <name>] [--out ./dir]
-```
-
-`--major` resolves that major's latest version first, so `--all` is implied; `--major` and `--ver` are mutually exclusive. Artifacts keep their sub-directory: `extras/X.dll` is written to `<out>/extras/X.dll`.
-
-## Local Wyn environments (Windows)
-
-The artifacts and the tool are cross-platform: runtime packages ship the RID assets for every platform they support (`runtimes/{linux*, osx, unix, win*}`, with `libSkiaSharp.so`/`.dylib`/`.dll` per platform), and an assembled environment is configured for the host it is built on — `Wyn.conf` uses that platform's path separators, and `Monitor/conf` is a junction on Windows or a directory symlink elsewhere. Which `runtimes/<rid>/native` variant is loaded is decided by the .NET runtime from the whole copied directory; the tool never selects a CPU architecture and never targets 32-bit Windows (`win32` is Node's name for Windows on x64, x86 and arm64 alike — the architecture is `process.arch`). `oss`/`az` only decide where the artifacts come from.
-
-```bash
-# Optionally pick one directory for every environment (stored in config.json)
-afm env root D:\wyn-envs     # validate, create if missing, remember
-afm env root                 # print it
-afm env root --json          # { configured, root, exists, configPath }
-afm env root --unset
-
-# Assemble a fresh embedded environment (nothing is started or registered as a Windows service)
-afm oss create-env D:\wyn-envs\demo --name demo --major 9.1 \
-  [--modules dashboard reporting] [--edition en] [--port 51980] [--dry-run]
-
-# With a configured environment root the path can be omitted
-afm oss create-env --name demo --major 9.1
-```
-
-Server, Monitor, Account, Dataset, AnalysisModel and CotWorker are always included. `--modules` is edition-scoped: **CN** offers `dashboard`, `reporting` and `data-monitoring`, **EN** additionally offers `sheets` and `documents` (smart documents, which pulls in the collaboration service it needs). Without `--port` the first free port in `51900`-`51980` is used; an explicit `--port` is used as given and fails on a conflict. `--dry-run` resolves everything and writes nothing. The result warns when the Server package ships no XSD for the detected configuration schema.
-
-```bash
-afm env list [--json]                            # state, port, edition, major, root, local overrides, PID
-afm env start   <name> [--foreground|--background]
-afm env stop    <name>
-afm env restart <name> [--foreground|--background]
-afm env delete  <name> [--yes]
-```
-
-* Background output is appended to `<root>\logs\server.stdout.log` and `server.stderr.log`.
-* `running` means the monitor process is alive — not that Wyn finished starting or that the port answers.
-* A stopped environment keeps its reserved port and name; nothing is reassigned automatically.
-* `delete` stops the environment, then removes its directory and its registry record; `--yes` is required when stdin is not a terminal.
-* Environments are listed from `~/.afm/environments.json` (`AFM_CONFIG_DIR` for another profile).
-
-## Update the modules of an environment
-
-```bash
-afm oss update-env <name> --modules dashboard                # latest for the recorded major
-afm oss update-env <name> --modules dashboard:0.1.12345      # pinned version
-afm oss update-env <name> --modules dashboard=D:\build\Wyn.Dashboards.Plugin.dll
-afm oss update-env <name> --modules all                      # every installed module except local ones
-afm oss update-env <name> --modules dashboard --dry-run
-```
-
-Remote updates download, verify (SHA256 + archive checks) and replace the deployed files; the environment must be observed `ready` or `stopped` (`running`/`unknown` is refused — stop it first). A **local source copies nothing** for plugins: the deployed `Plugins\<module>` directory is removed and `conf\Wyn.conf` is pointed straight at your build, so the Server loads it; restart the environment to load the change. Modules that were never installed are installed. `--modules` is required — name `all` or one or more modules.
-
-The **Server** is the exception: `--modules server=<build directory>` records a local Server build output, and `env start`/`env restart` copy it over the environment's `Server\` directory on every start (the environment's own `Server\appsettings.json` is kept). After the copy, the built-in payloads that live inside `Server\` are re-applied **from a local cache** — a start never downloads, and a missing cache entry is refused with the command that refreshes it. Because the copied build decides the runtime file versions, run `afm oss|az update-env <name> --modules all` once after a build whose dependencies changed: it refreshes the installed payloads from the recorded build directory and stores them in that cache. A remote `update-env <name> --modules server` deploys the published package again and clears the local source.
-
-**Every module can be refreshed, the core components included** — `server`, `monitoring`, `common`, `analysis`, `dashboard`, `reporting`, `data-monitoring`, `sheets`, `documents` and `collaboration` all go through the same path, and `all` covers them together (skipping the ones that have a local source). Refreshing `server` or `monitoring` is checked like a create: the package must ship the runtime assemblies and settings its service needs (the Server's required runtime files, and `Wyn.Configuration.dll` plus `appsettings.json` for the Monitor) and the `xsd/<schema>/Wyn.conf.xsd` for the configuration schema the environment already declares — a Monitor package without it is refused, a Server package without it only warns, because Wyn's configuration reader falls back to ordinary XML deserialization. Refresh the two in the same call when you can: they ship the schema assets for the same configuration, and a single-sided refresh is reported as a warning. The environment's own `Server\appsettings.json` is kept across the replacement (the Server package never deploys one), the Monitor's `conf` assets are merged into `conf\` and the `Monitor/conf` junction is recreated. A local source is refused for `monitoring` and `collaboration`: they are whole services, refreshed from artifacts only. `sheets` and `documents` still require an EN edition environment.
-
-A module can own several assemblies (`gces-common` = two plugins + one worker; `dashboard`/`reporting` = plugin + worker), so local sources resolve per assembly:
-
-| Spec | Selects |
-|---|---|
-| `dashboard=D:\build\Wyn.Dashboards.Plugin.dll` | the target whose file name matches |
-| `dashboard=D:\build\out` | every assembly of that module found in the directory |
-| `dashboard#Wyn.Dashboards.Worker.dll=D:\build\worker.dll` | that target explicitly |
-| repeated `common=` specs | one target each, as long as no target is selected twice |
-
-```bash
-afm oss update-env demo --modules \
-  common=D:\gces-common\src\Wyn.Dataset.Plugin\bin\release\net8.0\Wyn.Dataset.Plugin.dll \
-  common=D:\gces-common\src\Wyn.Account.Plugin\bin\release\net8.0\Wyn.Account.Plugin.dll \
-  common=D:\gces-common\src\Wyn.CotWorker\bin\release\net8.0\Wyn.CotWorker.dll
-```
-
-The override is recorded in the environment manifest (`moduleSources`) and shown by `env list` in a `local` column; switching the module back to a remote spec deletes the override and restores the deployed files.
-
-## Apply a local build while starting
-
-```bash
-afm env start   demo --background --modules dashboard=D:\build\Wyn.Dashboards.Plugin.dll
-afm env restart demo             --modules common=D:\build\common,common#Wyn.CotWorker.dll=D:\build\Wyn.CotWorker.dll
-```
-
-Same specs as `update-env`, but only local sources are accepted here (`env` has no cloud provider — use `update-env` for artifacts). `start` applies the override and then starts; `restart` stops, applies and starts again, which is the usual "rebuild, then reload" loop.
-
-## Local web interface
-
-```bash
-afm web                     # 127.0.0.1, OS-assigned port, opens your browser
-afm web --port 4599         # fixed port
-afm web --token <secret>    # reuse your own token instead of a generated one (>= 16 characters)
-afm web --no-open           # print the URL only
-```
-
-The page lists the registered environments — one row each, with its site link (`http://localhost:<port>`), a **复制** button for that address and a **打开目录** button that reveals the environment root in Explorer (Windows), Finder (macOS) or `xdg-open` (Linux) — and can create, start, stop, restart and delete them and update their modules. The create form and the update panel default to the **`oss`** provider, falling back to `az` only when OSS has no stored credentials, and the optional-module list follows the selected edition (CN: `dashboard`, `reporting`; EN: those plus `sheets` and `documents`). Creating and updating use the same code paths as `create-env`/`update-env`, including `--dry-run`. The 设置 dialog writes the same local profile the CLI uses, so a machine without a terminal session can still be prepared: the **environment root** (like `afm env root <path>`) and the **az/oss credentials** (like `afm az login` / `afm oss login`). Credentials are send-only — the page shows whether a provider is configured, never the SAS URL or the key.
-
-```json
-{
-  "host": "127.0.0.1",
-  "port": 4599,
-  "url": "http://127.0.0.1:4599/",
-  "tokenUrl": "http://127.0.0.1:4599/#token=<token>",
-  "token": "<token>"
-}
-```
-
-* **Loopback only.** The listener binds `127.0.0.1`; there is no option to expose it.
-* **Token on every request.** The page reads the token from the URL fragment (which browsers never send to the server), keeps it in `sessionStorage` and sends it as `X-AFM-Token`. `Authorization: Bearer <token>` also works. Comparisons are constant-time.
-* **Host and origin checks.** A request whose `Host` header is not `127.0.0.1:<port>` or `localhost:<port>` is refused (DNS rebinding), and no CORS header is ever sent, so another page cannot read a reply or send the token header. The page is served with a strict `Content-Security-Policy`.
-* **Long operations are jobs.** Create/update/delete/start/stop/restart answer `202` with a job id; the page polls `GET /api/jobs/<id>`. Mutations of one environment are serialized (a second request waits as `queued`), and the first `Ctrl+C` waits for running jobs before stopping so an interrupted `create-env` does not leave a reservation behind.
-* **Start always uses background mode** from the page — a foreground monitor would own the terminal the web server runs in. Use the CLI when you want foreground output.
-* Deleting from the page requires typing the environment name; it stops the verified monitor and removes the directory and the registry record, exactly like `env delete`.
-
-## Library
-
-
-```ts
-import { ArtifactClient, buildEnvironmentPlan, executeEnvironmentPlan } from '@guanjinke/artifact-client';
-
-const client = new ArtifactClient('oss', { keyId: 'id', key: 'secret', bucket: 'my-bucket' });
-
-await client.listPlugins({ includeSize: true });
-await client.listMajorVersions('myPlugin', { sortOrder: 'asc' });
-await client.getLatestVersion('gces-server', '9.1');
-await client.listArtifacts('gces-server', '9.1.21042', { includeSize: true });
-await client.uploadArtifact('myPlugin', '1.0.6', 'bundle.zip', './dist/bundle.zip');
-await client.updateLatestVersion('myPlugin', '9.1-hotfix1', '1.0.6');
-await client.downloadArtifact('myPlugin', '1.0.5', 'bundle.zip', './downloads');
-await client.downloadArtifactByPath('plugin_artifacts/myPlugin/1.0.5/bundle.zip', './downloads');
-const files = await client.downloadVersion('myPlugin', '1.0.5', './downloads');
-
-// Plan resolutely (no downloads or writes), then assemble and register an environment
-const plan = await buildEnvironmentPlan({ root: 'D:/wyn/demo', major: '9.1', modules: ['dashboard'] }, client);
-const result = await executeEnvironmentPlan(plan, { client });
-```
-
-| Method | Description |
-|---|---|
-| `listPlugins(opts?)` | List plugins (optionally with total size) |
-| `listMajorVersions(plugin, opts?)` | Majors with the version each one points at |
-| `getLatestVersion(plugin, major, opts?)` | Version a major currently points at |
-| `listMinorVersions(plugin, major, opts?)` | Versions under a major |
-| `listArtifacts(plugin, version, opts?)` | Files of a version (optionally with sizes) |
-| `uploadArtifact(plugin, version, name, localPath)` | Upload one file into a version directory |
-| `updateLatestVersion(plugin, major, version)` | Move a major's latest pointer |
-| `downloadArtifactByPath(fullPath, localDir)` | Download by full storage path |
-| `downloadArtifact(plugin, version, fileName, localDir)` | Download by name |
-| `downloadVersion(plugin, version, localDir)` | Download every file of a version |
-
-`client` is a small typed interface, so tests can inject a stub. Assembly, planning, listing and lifecycle all work on Windows, Linux and macOS: lifecycle uses the Windows backend on Windows and a POSIX backend (`/proc` on Linux, `ps` on macOS) elsewhere. Running an environment never needs administrator rights; only the process-identity check touches privileges, because Windows withholds the command line and executable path of a process owned by another account (a SYSTEM `WynService`, for instance). Such a process is attributed to an environment only when it carries that environment's recorded monitor PID, and it is reported in `afm env list` instead of blocking a start.
-
-## Notes
-
-* Stopping is a forced process-tree termination, not a graceful HTTP shutdown.
-* A missing or unknown process identity blocks start/stop/delete instead of guessing.
-* Version resolution never selects a different archive by size: only the exact expected file name is used.
-
-Design details, safety semantics and development notes live in the repository.
-
-MIT
+# @guanjinke/artifact-client
+
+Upload, browse and download build artifacts on **Azure Blob Storage** and **Aliyun OSS**, and build and manage local **Wyn environments** from those artifacts.
+
+Requires Node.js >= 20. `az` commands talk to Azure, `oss` commands to Aliyun OSS; below they are interchangeable unless noted.
+
+## Install
+
+```bash
+npm install -g @guanjinke/artifact-client
+afm --version
+```
+
+## Credentials
+
+```bash
+afm az login  --sasurl "https://<account>.blob.core.windows.net/<container>?<SAS>"
+afm oss login --keyid <id> --key <secret> [--bucket <bucket>] [--region oss-cn-hangzhou]
+
+# `--bucket` and `--region` are optional: a blank value is stored as the CLI's
+# built-in default, so the AccessKey pair alone is a complete OSS profile.
+
+# or pass them inline on any command: --sasurl, --keyid/--key/--bucket/--region
+afm az list-plugins --sasurl "https://..."
+
+afm az config show     # print the saved credentials
+afm az config clear    # remove them
+```
+
+Saved settings live in `~/.afm/config.json`; set `AFM_CONFIG_DIR` to use another directory.
+
+## Browse artifacts
+
+```bash
+afm az list-plugins [--size]
+afm az list-majors <plugin> [--size] [--sort asc|desc]
+afm az get-latest <plugin> <major> [--size] [--no-verify]
+afm az list-minors <plugin> <major> [--size] [--sort asc|desc]
+afm az list-artifacts <plugin> <version> [--size]
+```
+
+A **major** (`9.1`, `9.0`, `9.1-hotfix1`, `9.1-oem`, `dev`, ...) is a product label, not an artifact version. Each major owns a version file (`version9.1.txt`, `versiondev.txt`) that records the version it currently points at; `get-latest` reads it and warns on stderr when that version no longer holds artifacts (`--no-verify` skips the check).
+
+## Upload
+
+```bash
+# Write the file into the version directory (major pointers untouched)
+afm az upload <plugin> <version> <artifact-name> <local-file>
+
+# ... and record it as the latest of a major in the same step
+afm az upload <plugin> <version> <artifact-name> <local-file> --set-latest --major 9.1
+
+# Or move a major separately
+afm az set-latest <plugin> <major> <version> [--no-verify]
+```
+
+Uploading and moving a major are deliberately separate: a hotfix upload cannot accidentally move `version9.1.txt`.
+
+## Download
+
+```bash
+afm az download --path "<full/storage/path>"                     [--out ./dir]
+afm az download --plugin <plugin> --ver <version> --file <name>   [--out ./dir]
+afm az download --plugin <plugin> --ver <version> --all           [--out ./dir]
+afm az download --plugin <plugin> --major <major> [--file <name>] [--out ./dir]
+```
+
+`--major` resolves that major's latest version first, so `--all` is implied; `--major` and `--ver` are mutually exclusive. Artifacts keep their sub-directory: `extras/X.dll` is written to `<out>/extras/X.dll`.
+
+## Local Wyn environments (Windows)
+
+The artifacts and the tool are cross-platform: runtime packages ship the RID assets for every platform they support (`runtimes/{linux*, osx, unix, win*}`, with `libSkiaSharp.so`/`.dylib`/`.dll` per platform), and an assembled environment is configured for the host it is built on — `Wyn.conf` uses that platform's path separators, and `Monitor/conf` is a junction on Windows or a directory symlink elsewhere. Which `runtimes/<rid>/native` variant is loaded is decided by the .NET runtime from the whole copied directory; the tool never selects a CPU architecture and never targets 32-bit Windows (`win32` is Node's name for Windows on x64, x86 and arm64 alike — the architecture is `process.arch`). `oss`/`az` only decide where the artifacts come from.
+
+```bash
+# Optionally pick one directory for every environment (stored in config.json)
+afm env root D:\wyn-envs     # validate, create if missing, remember
+afm env root                 # print it
+afm env root --json          # { configured, root, exists, configPath }
+afm env root --unset
+
+# Assemble a fresh embedded environment (nothing is started or registered as a Windows service)
+afm oss create-env D:\wyn-envs\demo --name demo --major 9.1 \
+  [--modules dashboard reporting] [--edition en] [--port 51980] [--dry-run]
+
+# With a configured environment root the path can be omitted
+afm oss create-env --name demo --major 9.1
+```
+
+Server, Monitor, Account, Dataset, AnalysisModel and CotWorker are always included. `--modules` is edition-scoped: **CN** offers `dashboard`, `reporting` and `data-monitoring`, **EN** additionally offers `sheets` and `documents` (smart documents, which pulls in the collaboration service it needs). Without `--port` the first free port in `51900`-`51980` is used; an explicit `--port` is used as given and fails on a conflict. `--dry-run` resolves everything and writes nothing. The result warns when the Server package ships no XSD for the detected configuration schema.
+
+```bash
+afm env list [--json]                            # state, port, edition, major, root, local overrides, PID
+afm env start   <name> [--foreground|--background]
+afm env stop    <name>
+afm env restart <name> [--foreground|--background]
+afm env delete  <name> [--yes]
+```
+
+* Background output is appended to `<root>\logs\server.stdout.log` and `server.stderr.log`.
+* `running` means the monitor process is alive — not that Wyn finished starting or that the port answers.
+* A stopped environment keeps its reserved port and name; nothing is reassigned automatically.
+* `delete` stops the environment, then removes its directory and its registry record; `--yes` is required when stdin is not a terminal.
+* Environments are listed from `~/.afm/environments.json` (`AFM_CONFIG_DIR` for another profile).
+
+## Update the modules of an environment
+
+```bash
+afm oss update-env <name> --modules dashboard                # latest for the recorded major
+afm oss update-env <name> --modules dashboard:0.1.12345      # pinned version
+afm oss update-env <name> --modules dashboard=D:\build\Wyn.Dashboards.Plugin.dll
+afm oss update-env <name> --modules all                      # every installed module except local ones
+afm oss update-env <name> --modules dashboard --dry-run
+```
+
+Remote updates download, verify (SHA256 + archive checks) and replace the deployed files; the environment must be observed `ready` or `stopped` (`running`/`unknown` is refused — stop it first). A **local source copies nothing** for plugins: the deployed `Plugins\<module>` directory is removed and `conf\Wyn.conf` is pointed straight at your build, so the Server loads it; restart the environment to load the change. Modules that were never installed are installed. `--modules` is required — name `all` or one or more modules.
+
+The **Server** is the exception: `--modules server=<build directory>` records a local Server build output, and `env start`/`env restart` copy it over the environment's `Server\` directory on every start (the environment's own `Server\appsettings.json` is kept). After the copy, the built-in payloads that live inside `Server\` are re-applied **from a local cache** — a start never downloads, and a missing cache entry is refused with the command that refreshes it. Because the copied build decides the runtime file versions, run `afm oss|az update-env <name> --modules all` once after a build whose dependencies changed: it refreshes the installed payloads from the recorded build directory and stores them in that cache. A remote `update-env <name> --modules server` deploys the published package again and clears the local source.
+
+**Every module can be refreshed, the core components included** — `server`, `monitoring`, `common`, `analysis`, `dashboard`, `reporting`, `data-monitoring`, `sheets`, `documents` and `collaboration` all go through the same path, and `all` covers them together (skipping the ones that have a local source). Refreshing `server` or `monitoring` is checked like a create: the package must ship the runtime assemblies and settings its service needs (the Server's required runtime files, and `Wyn.Configuration.dll` plus `appsettings.json` for the Monitor) and the `xsd/<schema>/Wyn.conf.xsd` for the configuration schema the environment already declares — a Monitor package without it is refused, a Server package without it only warns, because Wyn's configuration reader falls back to ordinary XML deserialization. Refresh the two in the same call when you can: they ship the schema assets for the same configuration, and a single-sided refresh is reported as a warning. The environment's own `Server\appsettings.json` is kept across the replacement (the Server package never deploys one), the Monitor's `conf` assets are merged into `conf\` and the `Monitor/conf` junction is recreated. A local source is refused for `monitoring` and `collaboration`: they are whole services, refreshed from artifacts only. `sheets` and `documents` still require an EN edition environment.
+
+A module can own several assemblies (`gces-common` = two plugins + one worker; `dashboard`/`reporting` = plugin + worker), so local sources resolve per assembly:
+
+| Spec | Selects |
+|---|---|
+| `dashboard=D:\build\Wyn.Dashboards.Plugin.dll` | the target whose file name matches |
+| `dashboard=D:\build\out` | every assembly of that module found in the directory |
+| `dashboard#Wyn.Dashboards.Worker.dll=D:\build\worker.dll` | that target explicitly |
+| repeated `common=` specs | one target each, as long as no target is selected twice |
+
+```bash
+afm oss update-env demo --modules \
+  common=D:\gces-common\src\Wyn.Dataset.Plugin\bin\release\net8.0\Wyn.Dataset.Plugin.dll \
+  common=D:\gces-common\src\Wyn.Account.Plugin\bin\release\net8.0\Wyn.Account.Plugin.dll \
+  common=D:\gces-common\src\Wyn.CotWorker\bin\release\net8.0\Wyn.CotWorker.dll
+```
+
+The override is recorded in the environment manifest (`moduleSources`) and shown by `env list` in a `local` column; switching the module back to a remote spec deletes the override and restores the deployed files.
+
+## Apply a local build while starting
+
+```bash
+afm env start   demo --background --modules dashboard=D:\build\Wyn.Dashboards.Plugin.dll
+afm env restart demo             --modules common=D:\build\common,common#Wyn.CotWorker.dll=D:\build\Wyn.CotWorker.dll
+```
+
+Same specs as `update-env`, but only local sources are accepted here (`env` has no cloud provider — use `update-env` for artifacts). `start` applies the override and then starts; `restart` stops, applies and starts again, which is the usual "rebuild, then reload" loop.
+
+## Local web interface
+
+```bash
+afm web                     # 127.0.0.1, OS-assigned port, opens your browser
+afm web --port 4599         # fixed port
+afm web --token <secret>    # reuse your own token instead of a generated one (>= 16 characters)
+afm web --no-open           # print the URL only
+```
+
+The page lists the registered environments — one row each, with its site link (`http://localhost:<port>`), a **复制** button for that address and a **打开目录** button that reveals the environment root in Explorer (Windows), Finder (macOS) or `xdg-open` (Linux) — and can create, start, stop, restart and delete them and update their modules. The create form and the update panel default to the **`oss`** provider, falling back to `az` only when OSS has no stored credentials, and the optional-module list follows the selected edition (CN: `dashboard`, `reporting`; EN: those plus `sheets` and `documents`). Creating and updating use the same code paths as `create-env`/`update-env`, including `--dry-run`. The 设置 dialog writes the same local profile the CLI uses, so a machine without a terminal session can still be prepared: the **environment root** (like `afm env root <path>`) and the **az/oss credentials** (like `afm az login` / `afm oss login`). Credentials are send-only — the page shows whether a provider is configured, never the SAS URL or the key.
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 4599,
+  "url": "http://127.0.0.1:4599/",
+  "tokenUrl": "http://127.0.0.1:4599/#token=<token>",
+  "token": "<token>"
+}
+```
+
+* **Loopback only.** The listener binds `127.0.0.1`; there is no option to expose it.
+* **Token on every request.** The page reads the token from the URL fragment (which browsers never send to the server), keeps it in `sessionStorage` and sends it as `X-AFM-Token`. `Authorization: Bearer <token>` also works. Comparisons are constant-time.
+* **Host and origin checks.** A request whose `Host` header is not `127.0.0.1:<port>` or `localhost:<port>` is refused (DNS rebinding), and no CORS header is ever sent, so another page cannot read a reply or send the token header. The page is served with a strict `Content-Security-Policy`.
+* **Long operations are jobs.** Create/update/delete/start/stop/restart answer `202` with a job id; the page polls `GET /api/jobs/<id>`. Mutations of one environment are serialized (a second request waits as `queued`), and the first `Ctrl+C` waits for running jobs before stopping so an interrupted `create-env` does not leave a reservation behind.
+* **Start always uses background mode** from the page — a foreground monitor would own the terminal the web server runs in. Use the CLI when you want foreground output.
+* Deleting from the page requires typing the environment name; it stops the verified monitor and removes the directory and the registry record, exactly like `env delete`.
+
+## Library
+
+
+```ts
+import { ArtifactClient, buildEnvironmentPlan, executeEnvironmentPlan } from '@guanjinke/artifact-client';
+
+const client = new ArtifactClient('oss', { keyId: 'id', key: 'secret', bucket: 'my-bucket' });
+
+await client.listPlugins({ includeSize: true });
+await client.listMajorVersions('myPlugin', { sortOrder: 'asc' });
+await client.getLatestVersion('gces-server', '9.1');
+await client.listArtifacts('gces-server', '9.1.21042', { includeSize: true });
+await client.uploadArtifact('myPlugin', '1.0.6', 'bundle.zip', './dist/bundle.zip');
+await client.updateLatestVersion('myPlugin', '9.1-hotfix1', '1.0.6');
+await client.downloadArtifact('myPlugin', '1.0.5', 'bundle.zip', './downloads');
+await client.downloadArtifactByPath('plugin_artifacts/myPlugin/1.0.5/bundle.zip', './downloads');
+const files = await client.downloadVersion('myPlugin', '1.0.5', './downloads');
+
+// Plan resolutely (no downloads or writes), then assemble and register an environment
+const plan = await buildEnvironmentPlan({ root: 'D:/wyn/demo', major: '9.1', modules: ['dashboard'] }, client);
+const result = await executeEnvironmentPlan(plan, { client });
+```
+
+| Method | Description |
+|---|---|
+| `listPlugins(opts?)` | List plugins (optionally with total size) |
+| `listMajorVersions(plugin, opts?)` | Majors with the version each one points at |
+| `getLatestVersion(plugin, major, opts?)` | Version a major currently points at |
+| `listMinorVersions(plugin, major, opts?)` | Versions under a major |
+| `listArtifacts(plugin, version, opts?)` | Files of a version (optionally with sizes) |
+| `uploadArtifact(plugin, version, name, localPath)` | Upload one file into a version directory |
+| `updateLatestVersion(plugin, major, version)` | Move a major's latest pointer |
+| `downloadArtifactByPath(fullPath, localDir)` | Download by full storage path |
+| `downloadArtifact(plugin, version, fileName, localDir)` | Download by name |
+| `downloadVersion(plugin, version, localDir)` | Download every file of a version |
+
+`client` is a small typed interface, so tests can inject a stub. Assembly, planning, listing and lifecycle all work on Windows, Linux and macOS: lifecycle uses the Windows backend on Windows and a POSIX backend (`/proc` on Linux, `ps` on macOS) elsewhere. Running an environment never needs administrator rights; only the process-identity check touches privileges, because Windows withholds the command line and executable path of a process owned by another account (a SYSTEM `WynService`, for instance). Such a process is attributed to an environment only when it carries that environment's recorded monitor PID, and it is reported in `afm env list` instead of blocking a start.
+
+## Notes
+
+* Stopping is a forced process-tree termination, not a graceful HTTP shutdown.
+* A missing or unknown process identity blocks start/stop/delete instead of guessing.
+* Version resolution never selects a different archive by size: only the exact expected file name is used.
+
+Design details, safety semantics and development notes live in the repository.
+
+MIT

package/dist/cli/config-manager.d.ts

@@ -26,6 +26,9 @@ export declare function writeConfig(config: CLIConfig): void;
 export declare function saveAzureConfig(config: AzureConfig): void;
 /**
  * Save OSS authentication config.
+ *
+ * A blank bucket or region stores the configured default instead, so the profile
+ * can never end up with credentials but no bucket to use them against.
  */
 export declare function saveOSSConfig(config: OSSConfig): void;
 /**

package/dist/cli/config-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-manager.d.ts","sourceRoot":"","sources":["../../src/cli/config-manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAK7D;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAYD;;;GAGG;AACH,wBAAgB,UAAU,IAAI,SAAS,CAWtC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAGnD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAIzD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAIrD;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAGlC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAK1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C"}
+{"version":3,"file":"config-manager.d.ts","sourceRoot":"","sources":["../../src/cli/config-manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAM7D;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAYD;;;GAGG;AACH,wBAAgB,UAAU,IAAI,SAAS,CAWtC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAGnD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAIzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAQrD;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAGlC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAGvD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAK1D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C"}

package/dist/cli/config-manager.js

@@ -46,6 +46,7 @@ exports.clearEnvironmentRoot = clearEnvironmentRoot;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
+const defaults_1 = require("../defaults");
 const CONFIG_DIR_NAME = '.afm';
 const CONFIG_FILE_NAME = 'config.json';
 /**
@@ -108,10 +109,17 @@ function saveAzureConfig(config) {
 }
 /**
  * Save OSS authentication config.
+ *
+ * A blank bucket or region stores the configured default instead, so the profile
+ * can never end up with credentials but no bucket to use them against.
  */
 function saveOSSConfig(config) {
     const current = readConfig();
-    current.oss = config;
+    current.oss = {
+        ...config,
+        bucket: config.bucket?.trim() || defaults_1.DEFAULT_OSS_BUCKET,
+        region: config.region?.trim() || defaults_1.DEFAULT_OSS_REGION,
+    };
     writeConfig(current);
 }
 /**

package/dist/cli/config-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../../src/cli/config-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config-manager.js","sourceRoot":"","sources":["../../src/cli/config-manager.ts"],"names":[],"mappings":"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"}

package/dist/cli/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/cli/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAepC;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAkCvC"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/cli/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC;;;GAGG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAkCvC"}

package/dist/cli/setup.js

@@ -42,6 +42,7 @@ const stored_client_1 = require("./stored-client");
 const web_1 = require("./web");
 const version_1 = require("./version");
 const semver_1 = require("../utils/semver");
+const defaults_1 = require("../defaults");
 const plan_1 = require("../environment/plan");
 const manager_1 = require("../environment/manager");
 const update_1 = require("../environment/update");
@@ -197,8 +198,8 @@ function addSharedCommands(program, type) {
         .option('--sasurl <url>', 'Azure SAS URL (az only)')
         .option('--keyid <id>', 'OSS Key ID (oss only)')
         .option('--key <key>', 'OSS Key Secret (oss only)')
-        .option('--bucket <bucket>', 'OSS bucket name (oss only)')
-        .option('--region <region>', 'OSS region (oss only)')
+        .option('--bucket <bucket>', `OSS bucket name (oss only; default: ${defaults_1.DEFAULT_OSS_BUCKET})`)
+        .option('--region <region>', `OSS region (oss only; default: ${defaults_1.DEFAULT_OSS_REGION})`)
         .action((options) => {
         if (type === 'az') {
             if (!options.sasurl) {
@@ -580,11 +581,13 @@ function createClient(type, cliOptions, environment = false) {
             console.error('Error: OSS key ID and key are required. Provide --keyid and --key or run "afm oss login".');
             process.exit(1);
         }
+        // Bucket and region are optional in the profile and fall back to the
+        // configured defaults, so credentials alone are enough to use OSS.
         return new artifact_client_1.ArtifactClient('oss', {
             keyId,
             key,
-            bucket: cliOptions.bucket || ossStored?.bucket,
-            region: cliOptions.region || ossStored?.region,
+            bucket: cliOptions.bucket || ossStored?.bucket || defaults_1.DEFAULT_OSS_BUCKET,
+            region: cliOptions.region || ossStored?.region || defaults_1.DEFAULT_OSS_REGION,
             ...(basePrefix !== undefined ? { basePrefix } : {}),
         });
     }