@guanjinke/artifact-client 1.4.0 → 1.5.1

package/README.md

@@ -1,363 +1,186 @@
-# @guanjinke/artifact-client
-
-Artifact management client and CLI for Azure Blob Storage and Aliyun OSS.
-
-Manage plugin build artifacts stored in `plugin_artifacts/` — list plugins, versions, artifacts, upload, download, and record which version each product major version currently releases.
-
-## Installation
-
-```bash
-npm install @guanjinke/artifact-client
-```
-
-Requires Node.js >= 20.
-
-## Usage
-
-### As a Library
-
-```typescript
-import { ArtifactClient } from '@guanjinke/artifact-client';
-
-// Azure Storage
-const azClient = new ArtifactClient('az', {
-  sasUrl: 'https://<account>.blob.core.windows.net/<container>?<SAS token>',
-});
-
-// Aliyun OSS
-const ossClient = new ArtifactClient('oss', {
-  keyId: 'your-access-key-id',
-  key: 'your-access-key-secret',
-  bucket: 'your-bucket',
-  region: 'oss-cn-hangzhou', // optional, defaults to oss-cn-hangzhou
-});
-
-// List all plugins
-const plugins = await client.listPlugins();
-// [{ name: 'myPlugin', path: 'plugin_artifacts/myPlugin/' }, ...]
-
-// List plugins with sizes
-const pluginsWithSize = await client.listPlugins({ includeSize: true });
-
-// List major versions of a plugin
-const majors = await client.listMajorVersions('myPlugin');
-// [{ majorVersion: '1.0', latestVersion: '1.0.5', minorCount: 3, path: '...' }, ...]
-
-// List major versions sorted ascending
-const majorsAsc = await client.listMajorVersions('myPlugin', { sortOrder: 'asc' });
-
-// Get the latest version for a major
-const latest = await client.getLatestVersion('myPlugin', '1.0');
-// { version: '1.0.5', path: 'plugin_artifacts/myPlugin/1.0.5/' }
-
-// List all minor versions under a major
-const minors = await client.listMinorVersions('myPlugin', '1.0');
-// [{ version: '1.0.5', path: '...' }, { version: '1.0.4', path: '...' }, ...]
-
-// List artifacts in a specific version
-const artifacts = await client.listArtifacts('myPlugin', '1.0.5');
-// [{ name: 'bundle.zip', path: '...' }, ...]
-
-// ... including each file's size
-const artifactsWithSize = await client.listArtifacts('myPlugin', '1.0.5', { includeSize: true });
-// [{ name: 'bundle.zip', path: '...', sizeMB: 12.5 }, ...]
-
-// Upload an artifact into a version directory (a plain write: no major version
-// pointer is touched)
-await client.uploadArtifact('myPlugin', '1.0.6', 'bundle.zip', './dist/bundle.zip');
-
-// Separately, record it as the latest version of a product major version
-await client.updateLatestVersion('myPlugin', '9.1-hotfix1', '1.0.6');
-
-// Download by full path
-await client.downloadArtifactByPath(
-  'plugin_artifacts/myPlugin/1.0.5/bundle.zip',
-  './downloads'
-);
-
-// Download by name
-await client.downloadArtifact('myPlugin', '1.0.5', 'bundle.zip', './downloads');
-
-// Download all artifacts for a version
-const files = await client.downloadVersion('myPlugin', '1.0.5', './downloads');
-// ['bundle.zip', 'checksum.txt']
-```
-
-### As a CLI
-
-```bash
-# Login (saves credentials to ~/.afm/config.json; set AFM_CONFIG_DIR to use another directory)
-afm az login --sasurl "https://..."
-afm oss login --keyid "your-id" --key "your-key" --bucket "my-bucket"
-
-# Or pass credentials inline
-afm az list-plugins --sasurl "https://..."
-
-# List plugins
-afm az list-plugins
-afm az list-plugins --size
-
-# List major versions
-afm az list-majors myPlugin
-afm az list-majors myPlugin --size --sort asc
-
-# Get latest version for a major
-afm az get-latest myPlugin 1.0
-
-# List minor versions
-afm az list-minors myPlugin 1.0
-afm az list-minors myPlugin 1.0 --sort asc
-
-# List artifacts in a version
-afm az list-artifacts myPlugin 1.0.5
-afm az list-artifacts myPlugin 1.0.5 --size
-
-# Upload
-afm az upload myPlugin 1.0.6 bundle.zip ./dist/bundle.zip
-afm az set-latest myPlugin 1.0 1.0.6
-
-# Download by full path
-afm az download --path "plugin_artifacts/myPlugin/1.0.5/bundle.zip" --out ./downloads
-
-# Download by name
-afm az download --plugin myPlugin --ver 1.0.5 --file bundle.zip --out ./downloads
-
-# Download all artifacts for a version
-afm az download --plugin myPlugin --ver 1.0.5 --all --out ./downloads
-
-# Download the latest version of a major version (all artifacts by default)
-afm az download --plugin myPlugin --major 1.0 --out ./downloads
-
-# ... or a single artifact from that major's latest version
-afm az download --plugin myPlugin --major 1.0 --file bundle.zip --out ./downloads
-
-# Manage config
-afm az config show
-afm az config clear
-```
-
-#### OSS Commands
-
-Same as above, replace `az` with `oss`:
-
-```bash
-afm oss list-plugins --keyid "id" --key "secret"
-afm oss upload myPlugin 1.0.6 bundle.zip ./dist/bundle.zip
-afm oss set-latest myPlugin 9.1-hotfix1 1.0.6
-```
-
-## Major Versions and Channels
-
-A **product major version** (主版本号) is a label rather than a semver:
-
-| Major version | Meaning |
-|---|---|
-| `10.0`, `9.0` | first product major of the year |
-| `8.1`, `9.1`, `10.1` | second product major of the year |
-| `9.1-oem` | major version for a specific OEM customer |
-| `9.1-hotfix1` | hotfix major version built on top of `9.1` |
-| `dev` | development major version, tracked in `versiondev.txt` |
-
-- Every major version owns a version file `version<major>.txt` recording its latest artifact
-  version, and `get-latest <plugin> <major>` reads exactly that file — so
-  `afm oss get-latest gces-server 9.1-hotfix2` needs no special casing.
-- Artifact versions are **independent** of the major version: they usually repeat the major
-  version's first two segments, but a dev artifact may be `10.0.1` (identity artifacts stay
-  compatible with the license control system). Uploading a file and moving a major version's latest
-  version are therefore **separate steps** — `upload` only writes the file, while
-  `set-latest <plugin> <major> <version>` records a version as that major version's latest (or
-  `upload --set-latest --major <major>` does both at once). A hotfix upload can no longer move
-  `version9.1.txt` by accident, and a dev build such as `10.0.1` never lands in `version10.0.txt`.
-- `list-majors` reports every major version it finds — directory-derived majors and file-declared
-  channel majors — with the latest version each one points at. Channel majors (`minorCount: 0`)
-  publish into plain version directories, so their history cannot be enumerated; `list-minors
-  <channel>` reports the version that major currently points at.
-- A version file without a pointer is a reserved major version and is not listed.
-- `get-latest` checks that the version a major version points at actually holds artifacts and warns
-  on stderr when it does not — production still contains pointers to pruned versions — while still
-  printing the pointer. `--no-verify` skips that extra listing.
-- `set-latest` warns when the version holds no artifacts but records it anyway — a major version is
-  often published before every file has landed — and `--no-verify` skips that check too.
-- `download --plugin <plugin> --major <major>` needs no `--ver`: it resolves the major's latest
-  version first and then downloads all of that version's artifacts, so `--all` is implied.
-  `--file` narrows it to a single artifact of that version. `--major` and `--ver` are mutually
-  exclusive. Artifacts that live in a sub-directory keep it locally: `patched/X.dll` is written to
-  `<out>/patched/X.dll`.
-
-## Storage Layout
-
-```
-<container/bucket>/
-└── plugin_artifacts/
-    ├── pluginA/
-    │   ├── version1.0.txt          # Tracks latest 1.0.x version
-    │   ├── version9.1-hotfix1.txt  # Tracks latest version of the 9.1-hotfix1 major version
-    │   ├── versiondev.txt          # Tracks latest dev version
-    │   ├── 1.0.5/
-    │   │   ├── bundle.zip
-    │   │   └── checksum.txt
-    │   └── 1.0.6/
-    │       └── bundle.zip
-    └── pluginB/
-        └── ...
-```
-
-- **Version files** (`version<major>.txt`, `versiondev.txt`): track the latest full version per major version
-  - The dev major version is usually the whole `0.x` range: the dev pipeline publishes a plugin-specific minor
-    (`0.0`, `0.1`, `0.2` and `0.3` are all in use) and always tracks it in `versiondev.txt`, so
-    read it with `get-latest <plugin> dev` (the numeric `0.x` spelling is accepted as an alias).
-    Some plugins publish dev artifacts under a different core (the production `gcef-identity-service`
-    currently points `dev` at `8.1.7-beta`), which is exactly why the version file is authoritative.
-  - Azure: latest version stored in blob metadata (`latestversion`)
-  - OSS: latest version stored in object tag (`latestversion`)
-
-## API Reference
-
-### `ArtifactClient`
-
-| Method | Description |
-|---|---|
-| `listPlugins(opts?)` | List all plugins |
-| `listMajorVersions(plugin, opts?)` | List major versions with latest version and count |
-| `getLatestVersion(plugin, major, opts?)` | Get latest minor version for a major |
-| `listMinorVersions(plugin, major, opts?)` | List all minor versions under a major |
-| `listArtifacts(plugin, version, opts?)` | List all artifact files in a version |
-| `uploadArtifact(plugin, version, name, localPath)` | Upload a file into a version directory; major version pointers are left untouched |
-| `updateLatestVersion(plugin, major, version)` | Record a version as a major version's latest (creates `version<major>.txt` when absent) |
-| `downloadArtifactByPath(fullPath, localDir)` | Download by full storage path |
-| `downloadArtifact(plugin, version, fileName, localDir)` | Download by name |
-| `downloadVersion(plugin, version, localDir)` | Download all artifacts for a version |
-
-## Create a Wyn Environment
-
-`create-env` resolves and assembles a **fresh Windows embedded environment** without installing Windows services or starting anything. It supports product labels `9.1`, `9.1-*` and `dev`. Dry-run reports `schema: "pending"`; execution reads the monitoring bundle's XML template and accepts only verified V91/9.1 or V100/10.0, with matching Monitor XSD assets. Missing Server XSD assets produce a warning rather than preventing assembly. Numeric artifact versions never determine the schema. Other numeric product majors fail explicitly.
-
-A resolved dry-run is not proof that independently published packages are compatible. Some dev Server packages omit `xsd/V100/Wyn.conf.xsd`, while the Monitor template selects V100. Wyn's configuration reader falls back to ordinary XML deserialization when its XSD assets are absent. Assembly therefore records and returns a warning for missing Server XSD rather than rejecting that combination or copying schemas from another package. Monitor's matching XSD remains required. This does not verify the Server assembly's XML reader compatibility or successful runtime startup.
-
-
-```bash
-# Core environment only; Server, Account, Dataset, AnalysisModel and CotWorker are automatic
- afm oss create-env D:/wyn-core --name wyn-core --major 9.1
-
- # Resolve exact per-module artifacts; no downloads or filesystem writes
-afm oss create-env D:/wyn-test --name wyn-test --major 9.1 --modules dashboard,reporting --dry-run
-afm az create-env D:/wyn-test --name wyn-test --major dev --modules analysis --edition en --dry-run
-
-# Assemble a fresh environment (Windows only)
-afm oss create-env D:/wyn-test --name wyn-test --major 9.1 --modules dashboard reporting --port 51980
-
-# With a configured environment root (afm env root D:/wyn-envs) the path is optional:
-afm oss create-env --name wyn-test --major 9.1
-```
-
-The default edition is `cn`, profile is `embedded`, and Web/embedded identity port is `51980`. The core Wyn components—Server, Account, Dataset, AnalysisModel and CotWorker—are always included and do not need to be listed in `--modules`. Optional modules are `dashboard`, `reporting` and EN-only `sheets`. `documents` is deliberately rejected until its CollaborationService dependency and embedded configuration are verified. Monitoring is also always included to run the environment. Dashboard no longer requires a separate AnalysisModel selection. Module names may be space- or comma-separated. Each plugin resolves its major once, and only its exact runtime ZIP is selected: unrelated language, styles and support archives are never selected by size.
-
-Saved credentials and inline credential flags work as with other commands. This command honors saved `basePrefix` and `--base-prefix`; an explicit empty string selects the container/bucket root. Provider defaults are Azure `plugin_artifacts` and OSS root. Existing commands retain their current prefix behavior. The JSON plan includes exact remote object names and mappings, not credentials or a SAS URL.
-
-Console progress is written to stderr with elapsed time and artifact counts: version resolution, download, SHA256, ZIP validation/extraction, directory assembly, configuration generation and publication. Long stages emit a waiting message every 15 seconds; this is not a byte percentage. Stdout remains a single JSON plan/result, so redirecting stdout preserves machine-readable output. Library callers can opt into the same stage messages using the third `buildEnvironmentPlan` argument or `executeEnvironmentPlan`'s `onProgress` dependency; library calls remain silent by default.
-
-The target must be absent or empty, must not be a filesystem root or protected installed/system location, and must not have a linked/reparse-point ancestor. There is no overwrite or force option. Download, streaming ZIP extraction, assembly verification and configuration generation happen in owned sibling temporary directories. ZIP paths, case-insensitive conflicts, links, reserved Windows names and resource limits are checked for every entry, including unused support files. The defaults cap each archive at 100,000 entries and 20 GiB uncompressed. Final files are published exclusively without replacing racing files; failure removes only owned paths and preserves unrelated data.
-
-Server-root `appsettings.json` and `appsettings.Development.json` are excluded from deployment (case-insensitive) so bundled startup overrides cannot affect the generated environment. This does not remove Monitor settings, nested helper settings or other environment-specific settings, and does not modify the downloaded ZIP or existing environments.
-
-The canonical editable configuration is `<root>/conf/Wyn.conf`. `<root>/Monitor/conf` is a Windows directory junction to it because the monitoring process resolves configuration from its own working directory. Other monitoring-bundle `conf` files are preserved in the canonical directory. The environment contains explicit plugin/embedded worker lists, actual assembly names (including known reporting naming variants), SQLite server databases and DuckDB warehouse settings. Monitored worker services are disabled to avoid parallel launches while embedded Server loads the deployed worker assemblies.
-
-`environment.lock.json` records selections, independent resolved versions, SHA256 hashes of downloaded ZIPs and runtime framework requirements read from required `.runtimeconfig.json` files. No host license, database or sample data is copied. Optional theme recompilation/styles-cache, additional language archives, bootstrap/sample provisioning, standalone identity patches and service installation are outside this command. Successful assembly is **not** proof of license validity, database initialization or successful runtime startup. Review the generated requirements and provide the appropriate .NET runtimes and licensing before starting anything manually.
-
-### Environment Library API
-
-```typescript
-import { ArtifactClient, buildEnvironmentPlan, executeEnvironmentPlan } from '@guanjinke/artifact-client';
-
-const client = new ArtifactClient('oss', { keyId: 'id', key: 'secret' });
-const plan = await buildEnvironmentPlan({
-  root: 'D:/wyn-test', major: '9.1', modules: ['dashboard'],
-}, client);
-// Planning never downloads or writes; execution uses these exact resolved versions.
-const result = await executeEnvironmentPlan(plan, { client });
-console.log(result.root, result.requirements);
-```
-
-Both APIs accept the existing client through a small typed interface, enabling cloud-independent testing. Execution defaults to the host platform; the optional injected platform is intended for isolated layout tests, not a claim of cross-platform Wyn support.
-
-## Update an Existing Environment
-
-`update-env` replaces selected modules of an already registered environment, or points a module at a local developer build without copying any files:
-
-```bash
-afm oss update-env <name> --modules <spec...> [--dry-run]
-afm az  update-env <name> --modules <spec...> [--dry-run]
-```
-
-Specs are space- or comma-separated, and each entry has one of these forms:
-
-| Spec | Meaning |
-| --- | --- |
-| `all` | every configured module from remote, skipping modules that have a local source |
-| `dashboard` | latest artifact of that module for the environment's recorded major |
-| `dashboard:0.1.12345` | pinned version |
-| `dashboard=D:\build\Wyn.Dashboards.Plugin.dll` | local source (no download, no copy) |
-
-`all` must be used alone and covers exactly the modules that are both updateable and currently installed in that environment (`common`, `analysis`, plus any of `dashboard`/`reporting`/`sheets` it has). Modules with a local source are skipped and reported (manifest `moduleSources`, registry `localModules`, the result's `skipped` list and a stderr line); `server` and `monitoring` are never included. Because `all` only selects remote specs, it follows the remote state rule below and requires the environment to be `ready` or `stopped`. If nothing is left to update the command fails without writing.
-
-A spec may not combine a pinned version with a local source, duplicate modules in one call are refused, and the module name must be `dashboard`, `reporting`, `sheets`, `analysis` or `common`. `server` and `monitoring` are refused because they define the runtime and configuration schema (recreate the environment instead), `documents` stays unsupported, and `sheets` still requires an `en` edition environment. Updating a module that was never installed installs it: its plugin entry is added and the module is listed in the registry; a remote spec also adds the manifest artifact/download entries, while a local spec records only `moduleSources`/`localModules` (there is no downloaded artifact to describe).
-
-Remote updates resolve exactly one exact artifact name for the resolved version, download into a sibling staging workspace (`<dirname(root)>/.afm-env-*`), verify its SHA256, extract and validate it, check every mapping's source directory and that exactly one runtime assembly is present, and only then replace the module's deployed directories (`Plugins/<X>`, its worker directories, and `<root>/Web Contents` when the dashboard archive contains it). The plugin entry is rewritten as the normal relative `Plugins\<dest>\<assembly>` path and the deployment is recorded in the manifest and registry.
-
-Local source behavior is configuration-only:
-
-* Nothing is copied into or out of the environment.
-* The already deployed `Plugins/<destination>` directory is deleted so the stale artifact cannot be loaded twice; the worker directories are left alone.
-* `<root>/conf/Wyn.conf` `<Server><Plugins>` is rewritten to the **absolute** local DLL path (forward slashes are normalized) so the Server loads the developer build directly.
-* The override is recorded in `environment.lock.json` `moduleSources` and in the registry as `localModules` (shown by `env list` in a `local` column); `dashboard`, `reporting`, `analysis` and `sheets` are supported. `common` deploys two plugin directories and is rejected for local sources. A directory may be given instead of a DLL when it contains exactly one of the module's known plugin assemblies, and the DLL must be outside the deployed plugin directory.
-* Only configuration changed, so the environment must be **restarted** (`afm env restart <name>`) to load the build; the CLI never restarts it automatically.
-* Switching a module back to a remote spec deletes the override, restores the relative entry and copies the freshly downloaded artifact again.
-
-Configuration rewriting always parses `<root>/conf/Wyn.conf`, mutates only the `Plugins` `sys:string` list (a single string or an array are both accepted), rebuilds it with the same options the creation path uses, and validates the result with `XMLValidator` before writing. Dashboard stays the first `Plugins` entry and unrelated entries keep their order.
-
-State rules: a remote update requires the observed state `ready` or `stopped`; `running`/`unknown` are refused with a request to run `afm env stop <name>` first, because the deployed files may be in use. A local-only update may run while the environment is `running` (the CLI then reports that a restart is required), but `unknown` is always refused. `--dry-run` performs the spec, ownership, tree and state validation plus remote resolution, prints the planned changes and downloads or writes nothing. Progress and the restart reminder go to stderr; stdout remains a single JSON result. JSON and configuration writes go through `<file>.afm-tmp` followed by an atomic rename, and the staging workspace is always removed. Unlike `create`/`start`/`stop`/`restart`, `update-env` does not take the per-environment lifecycle lock — those state rules are its only guard, so do not run an update concurrently with a lifecycle command for the same environment.
-
-## Managed Local Environments
-
-Create a named environment with `node dist/cli.js oss create-env D:/wyn/demo --name demo --major 9.1` (use `az` similarly). `--name` is required for managed creation and names are case-insensitively unique. The environment path is optional once a unified environment root is configured (see below). `--port` defaults to `51980`; reserved or occupied ports fail without automatic reassignment. `--dry-run` checks options, registry conflicts and TCP availability without reserving or writing files.
-
-### Unified Environment Root
-
-Configure one directory for all environments so the path no longer has to be typed:
-
-```bash
-afm env root D:/wyn-envs   # validate, create if missing and remember the directory
-afm env root               # print the configured directory (path on stdout)
-afm env root --json        # script-friendly state: configured/root/exists/configPath
-afm env root --unset       # forget it; <root> is required again
-
-# No path needed: creates D:/wyn-envs/demo
-afm oss create-env --name demo --major 9.1
-```
-
-The setting is stored as an absolute path in `~/.afm/config.json` (`AFM_CONFIG_DIR` redirects the directory) alongside credentials, so it is per OS user/profile; credentials and other settings are preserved when it is set or cleared. Every new environment is created at `<environment root>/<name>`, and the name must be a single safe directory segment (`A-Za-z0-9`, `.`, `_`, `-`, max 64 characters), so it can never escape the root.
-
-The configured directory is re-validated on every use. It must not be a filesystem root, the user profile itself, the AFM configuration directory or one of its descendants, or a Windows/Program Files/SystemRoot location, and no existing ancestor may be a symlink or junction. `afm env root <path>` creates a missing directory and verifies it is a regular directory; `--dry-run` validates the configured root without creating anything. An explicit `<root>` argument still wins over the configured root; when it points outside the configured directory a note is printed to stderr and the environment is still registered normally.
-
-Registered environments live in `~/.afm/environments.json` (set `AFM_CONFIG_DIR` for an isolated profile); credentials and the optional unified environment root remain in `config.json`. Use `node dist/cli.js env list [--json]` (the table shows a `local` column listing modules with a local build override; the JSON rows carry `localModules`), `env root [<path>] [--unset] [--json]`, `env start <name> [--foreground|--background]`, `env stop <name>`, and `env restart <name>`. Background output is appended to `<root>/logs/server.stdout.log` and `server.stderr.log`; foreground Ctrl+C stops the verified monitor process tree before returning.
-
-Start defaults to foreground. Restart preserves the previous mode, falling back to foreground. A stopped environment keeps its reserved port until deletion. List includes only environments registered for the current user/profile; in table mode it also prints the configured environment root (if any) to stderr. Lifecycle stages, verified monitor PID/mode and background log paths are printed to stderr; stdout remains available for inherited foreground output or list JSON.
-
-Background mode starts the monitor in its own hidden console through a short launcher, then confirms the monitor by its exact command line (absolute DLL, `--RunAsMonitor`) before recording it; the recorded process is independent of the CLI, and its stdout/stderr are appended to the log files. This is required because `Wyn.Server` assigns `Console.Title` at the top of `Main` and throws `IOException` without an attached console, while a process that merely inherits the CLI's console does not outlive the CLI. Foreground mode inherits the terminal's console and stdio, so run it from a real console; if a start fails, the error includes the monitor's last log output and, when the log shows the `Console.Title` failure, points at that call. Command execution still uses the OS process query (`Get-CimInstance`); if that query is unavailable or fails twice, start/stop report an uncertain state instead of guessing.
-
-`env delete <name> --yes` stops the verified monitor, removes the owned environment directory and then removes its registry record. Without `--yes`, deletion requires a TTY confirmation. Existing directories created before managed registration are not adopted.
-
-
-Registered states are `creating`, `ready`, `running` and `stopped`. List checks live identity and also reports `unknown`, `identity-mismatch`, `missing` and `broken`; `running` means a verified monitor process, not HTTP readiness. Start/stop/restart are serialized per environment. Names, ports and overlapping roots are reserved atomically before cloud access; interrupted creation remains visible rather than silently releasing an active reservation. Creator command lines are stored as digests so inline credentials are not persisted.
-
-Startup requires the owned marker and manifest, Server DLL/runtimeconfig, and a configuration port matching the registry. Stop verifies PID, creation timestamp, executable and exact argument tokens, then uses forced Windows `taskkill /T /F` tree termination and confirms captured descendants exited. A final process identity recheck reduces PID reuse risk; Windows native process handles/Job Objects are not used, so hostile process reuse between inspection and `taskkill` is outside this guarantee. Unknown identity or failed tree confirmation retains the record and refuses deletion. Uncertain startup cleanup keeps a recovery identity in the registry and reports failure. If registry persistence also fails, it attempts to write `<root>/.afm-runtime-recovery.json`; any such file makes lifecycle operations uncertain and requires manual recovery. Durable identity storage cannot be guaranteed if both registry and environment filesystems are unwritable. A manual relative `dotnet Wyn.Server.dll` launch cannot be safely attributed from CIM metadata, so such an ambiguous candidate makes list/stop/delete report `unknown` and refuse; a start is still allowed because environments are only ever launched with an absolute DLL path, so that process cannot be the one being replaced.
-
-Deletion preserves the ownership marker and manifest while removing other payload entries. If payload removal fails, the registry and metadata remain for retry. If the final directory removal fails (for example an editor or terminal still has the folder open), the command retries briefly, then attempts exclusive metadata restoration and reports an actionable error that names the processes whose command line mentions the directory, states that metadata and the registry record were retained, and asks for the same `env delete <name>` command to be re-run after those holders are closed; it does not silently unregister a partial directory.
-
-Locks are exclusive and bounded, with no automatic stale-lock deletion. A terminated CLI can leave `registry.lock` or `env-<uuid>.lock` in the configuration directory. Recover manually only after positively establishing that its owning operation is no longer active; elapsed age alone is not sufficient. Reservation/process recovery may require manual inspection when Windows denies process metadata. No command automatically adopts old environments or scans arbitrary Wyn installs.
-
-The standalone `buildEnvironmentPlan`/`executeEnvironmentPlan` APIs retain their previous behavior without global registration; managed callers can use `EnvironmentManager` and inject registry/process/port adapters for isolated tests. Runtime management is Windows-only; metadata planning/listing can run elsewhere but unavailable process inspection is reported as uncertain.
-
-## License
-
-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: `patched/X.dll` is written to `<out>/patched/X.dll`.
+
+## Local Wyn environments (Windows)
+
+Assembling and running environments is Windows-only. `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` adds `dashboard`, `reporting` and (EN edition only) `sheets`. The default port is `51980`. `--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 configured 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.
+
+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.
+
+## 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. Environment APIs are Windows-only for execution; planning and listing work anywhere.
+
+## 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/environment.d.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { EnvironmentManager } from '../environment/manager';
 import { EnvironmentRecord } from '../environment/registry';
+import { EnvironmentUpdater } from '../environment/update';
 export declare function confirmDeletion(entry: EnvironmentRecord, yes: boolean): Promise<boolean>;
-export declare function addEnvironmentCommands(program: Command, factory?: () => EnvironmentManager): void;
+export declare function addEnvironmentCommands(program: Command, factory?: () => EnvironmentManager, updaterFactory?: () => EnvironmentUpdater): void;
 //# sourceMappingURL=environment.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/cli/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAW,MAAM,yBAAyB,CAAC;AAQrE,wBAAsB,eAAe,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9F;AA0CD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,MAAM,kBAAoG,GAAG,IAAI,CAoBlL"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/cli/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAW,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAoB,MAAM,uBAAuB,CAAC;AA+C7E,wBAAsB,eAAe,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9F;AA0CD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,GAAE,MAAM,kBAAoG,EAAE,cAAc,GAAE,MAAM,kBAAoG,GAAG,IAAI,CA4C9S"}