@guanjinke/artifact-client 1.13.0 → 1.14.0

package/README.md

@@ -1,217 +1,219 @@
-# @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**: 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.
-
-**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 `server`, `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]
+
+# 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/environment/artifact-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Local cache of downloaded artifacts.
+ *
+ * A local Server build replaces `Server/` on every start, which throws away the
+ * built-in resource tree and the patched file. Re-applying them must not touch the
+ * network: the `env` command group has no cloud provider, and a start should not
+ * depend on the cloud being reachable. Create and update therefore store every
+ * artifact they download here, keyed by the provider-side identity, and the start
+ * path reads only from this cache.
+ *
+ * Layout: `<config directory>/cache/artifacts/<plugin>/<version>/<object name>`
+ * (object names may contain sub-directories, e.g. `patched/X.dll`), where the
+ * config directory is `AFM_CONFIG_DIR` or `~/.afm`. The provider and version are
+ * internal: nothing here is echoed to the user.
+ */
+export declare function artifactCacheDirectory(): string;
+/** Where one cached object lives; exported for tests and diagnostics. */
+export declare function cachedArtifactPath(plugin: string, version: string, name: string): string;
+/**
+ * A cached object, or `undefined` when it is absent, not a regular file, or does
+ * not match the recorded SHA256. A mismatching file is treated as absent: the next
+ * create or update overwrites it, and a start refuses instead of deploying bytes
+ * nobody verified.
+ */
+export declare function cachedArtifact(plugin: string, version: string, name: string, sha256?: string): Promise<string | undefined>;
+/**
+ * Store one downloaded artifact under its provider-side identity.
+ *
+ * Copies through a uniquely named `.afm-tmp` sibling and an atomic rename, so a
+ * concurrent reader never sees a partial object and a failed write leaves no
+ * temporary file behind. An existing object with the same hash is kept as it is.
+ */
+export declare function storeArtifact(plugin: string, version: string, name: string, sourceFile: string, sha256: string): Promise<void>;
+/** Best-effort variant: caching must never fail a create or an update. */
+export declare function rememberArtifact(plugin: string, version: string, name: string, sourceFile: string, sha256: string): Promise<void>;
+//# sourceMappingURL=artifact-cache.d.ts.map

package/dist/environment/artifact-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-cache.d.ts","sourceRoot":"","sources":["../../src/environment/artifact-cache.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAqBD,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAExF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAMhI;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYpI;AAED,0EAA0E;AAC1E,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvI"}