@guanjinke/artifact-client 1.7.1 → 1.8.0

package/dist/environment/update.js

@@ -42,10 +42,13 @@ const fast_xml_parser_1 = require("fast-xml-parser");
 const catalog_1 = require("./catalog");
 const archive_1 = require("./archive");
 const builder_1 = require("./builder");
+const config_1 = require("./config");
+const plan_1 = require("./plan");
 const registry_1 = require("./registry");
 const validate_1 = require("./validate");
 const process_1 = require("./process");
 const posix_process_1 = require("./posix-process");
+const package_resource_1 = require("./package-resource");
 const atomic_1 = require("../utils/atomic");
 const local_path_1 = require("../utils/local-path");
 /** Same parser options as the creation path, so a rewrite round-trips identically. */
@@ -54,19 +57,48 @@ const builderOptions = { ignoreAttributes: false, format: true, suppressEmptyNod
 const windowsPath = (value, platform) => (0, local_path_1.nativeSeparators)(value, platform);
 /** The separator the recorded entries use on the target platform. */
 const separatorOf = (platform) => (platform === 'win32' ? '\\' : '/');
-/** Modules `update-env` may replace; exported so the web interface lists the same set. */
-exports.updatableModules = ['dashboard', 'reporting', 'sheets', 'documents', 'analysis', 'common'];
+/** Every catalog module can be updated remotely; local overrides are excluded per environment. */
+exports.updatableModules = Object.keys(catalog_1.catalog).sort();
+/**
+ * Server-root settings the environment owns.
+ *
+ * `create-env` never copies them out of the archive, because bundled startup
+ * overrides must not decide how a generated environment runs. An update replaces
+ * the whole `Server` directory, so it carries the deployed files across the
+ * replacement instead of deleting them with the old version.
+ */
+const serverOwnedFiles = ['appsettings.json', 'appsettings.development.json'];
+/**
+ * Package files a staged artifact must provide before it may replace a deployed
+ * module. `create-env` checks the same ones while it assembles an environment, so
+ * an update cannot install something a fresh environment would have been refused.
+ */
+const requiredPackageFiles = {
+    server: ['Wyn.Identity.Service.dll'],
+    monitoring: ['Wyn.Configuration.dll', 'appsettings.json'],
+};
+/**
+ * Package entries an update must not copy over a deployed directory.
+ *
+ * Besides the environment-owned Server settings, monitoring's own `conf`
+ * directory is excluded: its assets are merged into the canonical `conf/` and the
+ * directory itself has to become a junction to `conf/` again, not a second copy
+ * of the template the Monitor would then resolve configuration from.
+ */
+const excludedCopyNames = (mapping) => mapping.role === 'server' ? [...serverOwnedFiles] : mapping.role === 'monitor' ? ['conf'] : [];
+/**
+ * The modules a selection may name, from the same table `create-env` and the web
+ * interface read.
+ *
+ * Reading it through the call keeps this module loadable on its own: the policy
+ * is only needed while an update records a module it installs for the first time.
+ */
+const selectableModules = () => new Set([...new Set(Object.values(plan_1.optionalModulesByEdition).flat())]);
 const installationDirectory = (root, destination) => path.join(root, ...destination.split('/'));
 function validateUpdatableModule(module) {
-    if (exports.updatableModules.includes(module))
+    if (Object.prototype.hasOwnProperty.call(catalog_1.catalog, module))
         return;
-    if (module === 'server')
-        throw new Error('Module server cannot be updated: it defines the environment runtime and configuration schema. Recreate the environment with create-env instead.');
-    if (module === 'monitoring')
-        throw new Error('Module monitoring cannot be updated: it defines the configuration schema and monitor runtime. Recreate the environment with create-env instead.');
-    if (module === 'collaboration')
-        throw new Error('Module collaboration is deployed together with documents by create-env and the Server loads it from its own configuration entry; it is not updated on its own. Update `documents`, or recreate the environment.');
-    throw new Error(`Unsupported module "${module}": updateable modules are dashboard, reporting, sheets, documents, analysis and common.`);
+    throw new Error(`Unsupported module "${module}": supported modules are ${Object.keys(catalog_1.catalog).sort().join(', ')}.`);
 }
 /** `all` is the only allowed pseudo-module: every configured module from remote. */
 const allModules = 'all';
@@ -213,6 +245,12 @@ function stringList(raw) {
         throw new Error('Invalid environment configuration.');
     return list;
 }
+/**
+ * One recorded module list of the manifest, or undefined when the environment
+ * records none. A field of the wrong shape is treated as absent rather than as an
+ * error: the update only ever adds to these lists.
+ */
+const stringListOrUndefined = (raw) => Array.isArray(raw) && raw.every(item => typeof item === 'string') ? [...raw] : undefined;
 /** Replace or append one `<sys:string>` path list, matching by destination or assembly name. */
 function rewritePathList(values, entries, platform) {
     const strings = values.map(value => value.trim());
@@ -246,7 +284,10 @@ function rewritePathList(values, entries, platform) {
  * is returned. Dashboard stays the first `Plugins` entry; every other entry keeps
  * its order. A worker service keeps all of its other fields, including
  * `Disabled`; a configuration without that node is updated through
- * `<PluginWorkers>` alone.
+ * `<PluginWorkers>` alone. The Server service is kept in step the same way a
+ * worker is, and a native service the environment does not declare yet gets the
+ * empty node `create-env` writes, so a freshly installed collaboration service is
+ * actually loaded.
  */
 function patchEnvironmentConfiguration(xml, entries, platform = process.platform) {
     if (typeof xml !== 'string' || /<!DOCTYPE|<!ENTITY/i.test(xml) || fast_xml_parser_1.XMLValidator.validate(xml) !== true)
@@ -255,7 +296,7 @@ function patchEnvironmentConfiguration(xml, entries, platform = process.platform
     const server = document?.SystemConfig?.Services?.Server;
     if (!server || typeof server !== 'object' || Array.isArray(server))
         throw new Error('Environment configuration has no Server service.');
-    const pluginEntries = entries.filter(entry => entry.role !== 'worker');
+    const pluginEntries = entries.filter(entry => entry.role === undefined || entry.role === 'plugin');
     if (server.Plugins !== undefined || pluginEntries.length) {
         const plugins = server.Plugins === undefined || server.Plugins === '' ? {} : server.Plugins;
         if (typeof plugins !== 'object' || Array.isArray(plugins))
@@ -278,18 +319,29 @@ function patchEnvironmentConfiguration(xml, entries, platform = process.platform
             throw new Error('Invalid environment configuration.');
         pluginWorkers['sys:string'] = rewritePathList(stringList(pluginWorkers['sys:string']), workers, platform);
         server.PluginWorkers = pluginWorkers;
-        const services = document?.SystemConfig?.Services;
-        for (const entry of workers) {
-            if (!entry.service || !services || typeof services !== 'object' || Array.isArray(services))
-                continue;
-            const service = services[entry.service];
-            if (!service || typeof service !== 'object' || Array.isArray(service))
+    }
+    // Every entry a service starts from an assembly: the embedded workers and the
+    // Server itself. Each service keeps all of its other fields, including
+    // `Disabled` and the Server's `Urls` and storage settings.
+    const hosted = entries.filter(entry => (entry.role === 'worker' || entry.role === 'server') && entry.service);
+    // A native out-of-process service carries no assembly and is declared empty,
+    // exactly like the product's own `conf/Wyn.conf`: the Server loads it itself.
+    const declared = entries.filter(entry => entry.role === 'service' && entry.service);
+    const services = document?.SystemConfig?.Services;
+    if ((hosted.length || declared.length) && services && typeof services === 'object' && !Array.isArray(services)) {
+        const nodes = services;
+        for (const entry of declared)
+            if (nodes[entry.service] === undefined)
+                nodes[entry.service] = {};
+        for (const entry of hosted) {
+            const node = nodes[entry.service];
+            if (!node || typeof node !== 'object' || Array.isArray(node))
                 continue;
-            const node = service;
-            // The worker is loaded from the path list above and uses its own directory
+            const fields = node;
+            // The service is loaded from the path list above and uses its own directory
             // as its base directory: keep the service in step without touching Disabled.
-            node.WorkingDirectory = windowsPath((0, local_path_1.directoryOf)(entry.path, platform), platform);
-            node.Assembly = (0, local_path_1.baseNameOf)(entry.path);
+            fields.WorkingDirectory = windowsPath((0, local_path_1.directoryOf)(entry.path, platform), platform);
+            fields.Assembly = (0, local_path_1.baseNameOf)(entry.path);
         }
     }
     const output = new fast_xml_parser_1.XMLBuilder(builderOptions).build(document);
@@ -330,6 +382,10 @@ async function readManifest(root) {
     }
     if (manifest.selectedModules !== undefined && (!Array.isArray(manifest.selectedModules) || manifest.selectedModules.some(module => typeof module !== 'string')))
         throw new Error('Environment manifest is unreadable.');
+    // Only the entry name is required: the resource list is written by this package
+    // for the package's own trees, and unknown extra fields are preserved as-is.
+    if (manifest.resources !== undefined && (!Array.isArray(manifest.resources) || manifest.resources.some(resource => !resource || typeof resource !== 'object' || Array.isArray(resource) || typeof resource.name !== 'string')))
+        throw new Error('Environment manifest is unreadable.');
     if (manifest.moduleSources !== undefined && (!manifest.moduleSources || typeof manifest.moduleSources !== 'object' || Array.isArray(manifest.moduleSources)))
         throw new Error('Environment manifest is unreadable.');
     for (const source of Object.values(manifest.moduleSources ?? {})) {
@@ -417,6 +473,8 @@ async function stageRemoteArtifact(client, artifact, workspace, onProgress) {
             const source = path.join(expanded, mapping.source);
             if (!(await fs.lstat(source)).isDirectory())
                 throw new Error('Required source directory missing.');
+            if (mapping.role === 'service' && mapping.assemblies.length === 0)
+                continue;
             const present = [];
             for (const name of mapping.assemblies) {
                 try {
@@ -431,6 +489,12 @@ async function stageRemoteArtifact(client, artifact, workspace, onProgress) {
             if (present.length !== 1)
                 throw new Error(`Expected one runtime assembly in ${mapping.destination || 'root'}.`);
             assemblies.set(mapping.destination, present[0]);
+            // A plugin is loaded into the Server's own runtime; every other managed
+            // entry point is started by the Monitor and needs its own runtimeconfig for
+            // the .NET host to resolve the framework at all — exactly what create-env
+            // requires before it deploys one.
+            if (mapping.role !== 'plugin')
+                await (0, builder_1.regularFile)(path.join(source, present[0].replace(/\.dll$/, '.runtimeconfig.json')));
         }
         onProgress?.(`${label}: Archive and layout checks complete`);
         return { ...artifact, sha256, expanded, assemblies };
@@ -439,6 +503,96 @@ async function stageRemoteArtifact(client, artifact, workspace, onProgress) {
         throw new Error(`Module update failed for ${artifact.plugin}/${artifact.version}/${artifact.name} (download, archive or layout): ${error.message}`);
     }
 }
+/**
+ * The configuration schema this environment already runs.
+ *
+ * `create-env` recorded the schema it detected from the Monitor template in the
+ * manifest; an environment whose manifest predates the field falls back to the
+ * namespace its live `conf/Wyn.conf` declares. A Server or Monitor update needs
+ * this to check that the new package ships the matching XSD assets.
+ */
+function environmentSchema(manifest, configuration) {
+    if (manifest.schema === 'V91' || manifest.schema === 'V100')
+        return manifest.schema;
+    try {
+        return (0, config_1.detectConfigurationSchema)(configuration);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Check a staged Server or Monitor package against the deployed environment.
+ *
+ * `create-env` verifies the same things while it assembles: the Server's
+ * identity service, the Monitor's configuration assembly and settings, and the
+ * `xsd/<schema>/Wyn.conf.xsd` both packages ship for the configuration schema the
+ * environment declares. A Server package may legitimately omit its XSD — Wyn's
+ * configuration reader falls back to ordinary XML deserialization — which
+ * `create-env` records as a warning rather than rejecting, so the update keeps
+ * that policy. Returns the warning text, or undefined when the package is
+ * complete.
+ */
+async function verifyStagedPackage(module, staged, schema) {
+    const label = `${staged.plugin}/${staged.version}/${staged.name}`;
+    for (const name of requiredPackageFiles[module] ?? []) {
+        try {
+            await (0, builder_1.regularFile)(path.join(staged.expanded, name));
+        }
+        catch {
+            throw new Error(`Module update failed for ${label}: the package is missing ${name}.`);
+        }
+    }
+    const relative = `xsd/${schema}/Wyn.conf.xsd`;
+    try {
+        await (0, builder_1.regularFile)(path.join(staged.expanded, relative));
+        return undefined;
+    }
+    catch (error) {
+        if (module === 'server' && error.code === 'ENOENT') {
+            return `Server package ${label} is missing ${relative}; Server will skip XSD validation. XML reader compatibility and runtime startup have not been verified.`;
+        }
+        throw new Error(`Configuration schema validation failed for ${label}: ${module === 'server' ? 'Server' : 'Monitor'} package is missing ${relative}.`);
+    }
+}
+/** Copy a tree over an existing one, replacing files instead of refusing a collision. */
+async function overlayTree(source, destination) {
+    await fs.mkdir(destination, { recursive: true });
+    for (const entry of await fs.readdir(source, { withFileTypes: true })) {
+        const from = path.join(source, entry.name);
+        const to = path.join(destination, entry.name);
+        if (entry.isDirectory())
+            await overlayTree(from, to);
+        else if (entry.isFile())
+            await fs.copyFile(from, to);
+        else
+            throw new Error('Unexpected link in extracted archive.');
+    }
+}
+/**
+ * Merge a monitoring package's `conf` assets into the canonical configuration
+ * directory.
+ *
+ * `create-env` moves everything but the `Wyn.conf` template out of the Monitor
+ * package and leaves the environment's own `conf/Wyn.conf` as the single editable
+ * configuration, so the update refreshes the package's assets in place and never
+ * touches that file. An asset the new package no longer ships stays where it is:
+ * the directory also holds whatever the environment itself added.
+ */
+async function mergeConfigurationAssets(source, destination) {
+    for (const entry of await fs.readdir(source, { withFileTypes: true })) {
+        if (entry.name.toLowerCase() === 'wyn.conf')
+            continue;
+        const from = path.join(source, entry.name);
+        const to = path.join(destination, entry.name);
+        if (entry.isDirectory())
+            await overlayTree(from, to);
+        else if (entry.isFile())
+            await fs.copyFile(from, to);
+        else
+            throw new Error('Unexpected link in extracted archive.');
+    }
+}
 /** Mappings of one module that a local source may override. */
 const localMappings = (module) => catalog_1.catalog[module].mappings.filter(mapping => mapping.role === 'plugin' || mapping.role === 'worker');
 const expectedAssemblies = (module) => [...new Set(localMappings(module).flatMap(mapping => mapping.assemblies))];
@@ -463,6 +617,11 @@ function mappingForAssembly(module, assembly) {
  */
 async function resolveLocalSource(entry, module, assembly, input) {
     const mappings = localMappings(module);
+    // The Server, Monitor and collaboration deployments are whole services, not a
+    // plugin the Server loads: a developer build has no place to point the
+    // configuration at, so they are refreshed from their artifact only.
+    if (!mappings.length)
+        throw new Error(`Module ${module} is deployed from its artifact only: it has no plugin or worker assembly a local build could replace. Update it from a remote artifact, or recreate the environment with create-env.`);
     const source = path.resolve(input);
     const stat = await lstatOrUndefined(source);
     if (!stat)
@@ -546,12 +705,14 @@ class EnvironmentUpdater {
     registry;
     processes;
     platform;
+    bundledResources;
     onProgress;
     constructor(dependencies = {}) {
         this.dependencies = dependencies;
         this.registry = dependencies.registry ?? new registry_1.EnvironmentRegistry();
         this.processes = dependencies.processes ?? (process.platform === 'win32' ? new process_1.WindowsProcessBackend() : new posix_process_1.PosixProcessBackend());
         this.platform = dependencies.platform ?? process.platform;
+        this.bundledResources = dependencies.bundledResourcesDirectory ?? (0, package_resource_1.bundledResourcesDirectory)();
         this.onProgress = dependencies.onProgress;
     }
     async update(name, specs, clientFactory, options = {}) {
@@ -559,8 +720,9 @@ class EnvironmentUpdater {
         const onProgress = options.onProgress ?? this.onProgress;
         onProgress?.('Validating module specs');
         let parsed = normalizeModuleSpecs(specs);
-        if (!parsed.length)
-            throw new Error('At least one module spec is required: use --modules all, dashboard, reporting or dashboard=D:\\path\\Wyn.Dashboards.Plugin.dll.');
+        // No module spec is a valid request: it (re)lays out the bundled resources
+        // alone, which is how an environment created before they were bundled gets
+        // them without touching a single module.
         const entry = await this.registry.get(name);
         onProgress?.(`Validating environment ${entry.name} at ${entry.root}`);
         await (0, validate_1.validateEnvironmentRoot)(entry, this.registry.directory);
@@ -580,7 +742,7 @@ class EnvironmentUpdater {
                     skipped.push({ module, reason: 'local' });
             const selected = configured.filter(module => !localModules.has(module));
             if (!selected.length)
-                throw new Error(`Module spec all matched no updatable modules: ${configured.length ? configured.map(module => `${module} has a local source`).join('; ') : 'no configured module is updateable (server and monitoring are never updated)'}.`);
+                throw new Error(`Module spec all matched no updatable modules: ${configured.length ? configured.map(module => `${module} has a local source`).join('; ') : 'this environment has no installed module to refresh'}.`);
             parsed = selected.map(module => ({ module }));
             onProgress?.(`Updating all configured modules from remote: ${selected.join(', ')}${skipped.length ? ` (skipping local: ${skipped.map(item => item.module).join(', ')})` : ''}`);
         }
@@ -617,10 +779,39 @@ class EnvironmentUpdater {
             throw new Error(`Cannot update modules from a remote source while ${entry.name} is ${state}: deployed files may be in use. Run \`afm env stop ${entry.name}\` first.`);
         if (!remote.length && state !== 'ready' && state !== 'stopped' && state !== 'running')
             throw new Error(`Cannot update modules while ${entry.name} is ${state}: the runtime identity must be verified before its files are changed. Run \`afm env stop ${entry.name}\` first.`);
+        // The packaged 3D scene assets belong to every environment, not only to one
+        // that create-env assembled: the plan below finds the files an environment is
+        // still missing (or that differ) and the apply writes them with the rest of
+        // the update. Planning touches nothing and runs before any download or write,
+        // so an incomplete installation fails loudly with the path it expected and
+        // leaves the environment exactly as it was.
+        //
+        // The assets live at `Server/wwwroot/3DScene`, so refreshing the server
+        // module removes the whole tree they are in. Plan every packaged file as
+        // missing in that case: comparing against the content that is about to be
+        // deleted would report every file identical and lay nothing out at all.
+        const refreshesServer = remote.some(spec => spec.module === 'server');
+        const resourceSource = (0, package_resource_1.bundledResourceDirectory)(package_resource_1.sceneResourceName, this.bundledResources);
+        const resourceDestination = path.join(entry.root, ...package_resource_1.sceneResourceDestination.split('/'));
+        onProgress?.(`Checking bundled 3D scene resources in ${package_resource_1.sceneResourceDestination}`);
+        const resourcePlan = await (0, package_resource_1.planBundledResource)(resourceSource, resourceDestination, refreshesServer);
+        const resourceWrites = resourcePlan.added + resourcePlan.updated;
+        const resource = { name: package_resource_1.sceneResourceName, source: resourceSource, destination: package_resource_1.sceneResourceDestination, files: resourcePlan.files.length, added: resourcePlan.added, updated: resourcePlan.updated };
+        const resourceSummary = `${resourcePlan.files.length - resourceWrites} identical, ${resourcePlan.added} missing, ${resourcePlan.updated} different`;
+        onProgress?.(`Bundled 3D scene resources in ${package_resource_1.sceneResourceDestination}: ${dryRun ? 'dry run; ' : ''}${resourceSummary}`);
         const downloads = [...(manifest.downloads ?? [])];
-        const selectedModules = manifest.selectedModules === undefined ? undefined : [...manifest.selectedModules];
+        const selectedModules = stringListOrUndefined(manifest.selectedModules);
+        const autoAddedModules = stringListOrUndefined(manifest.autoAddedModules);
         const moduleSources = { ...(manifest.moduleSources ?? {}) };
-        const workspace = remote.length && !dryRun ? await fs.mkdtemp(path.join(path.dirname(entry.root), '.afm-env-')) : undefined;
+        // What a fresh environment would have selected for itself. An update records
+        // a first install the way `create-env` does: a selectable module joins the
+        // selection, a core component or an automatic dependency is added instead.
+        const selectable = selectableModules();
+        // The manifest records the .NET requirements read from each artifact's
+        // runtimeconfig files, so an update replaces the entries of the modules it
+        // refreshes and leaves every other module's alone.
+        let requirements = Array.isArray(manifest.requirements) ? manifest.requirements.filter((line) => typeof line === 'string') : [];
+        const workspace = !dryRun && (remote.length > 0 || resourceWrites > 0) ? await fs.mkdtemp(path.join(path.dirname(entry.root), '.afm-env-')) : undefined;
         const warnings = [];
         try {
             const resolved = new Map();
@@ -636,6 +827,23 @@ class EnvironmentUpdater {
                         staged.set(spec.module, await stageRemoteArtifact(client, resolved.get(spec.module), workspace, onProgress));
             }
             const configured = await fs.readFile(path.join(entry.root, 'conf', 'Wyn.conf'), 'utf8');
+            // A Server or Monitor package is only usable when it still serves the
+            // configuration schema this environment runs, so both are checked against
+            // the deployed schema before anything is planned around them.
+            const schema = remote.some(spec => spec.module === 'server' || spec.module === 'monitoring')
+                ? environmentSchema(manifest, configured)
+                : undefined;
+            if (remote.some(spec => spec.module === 'server' || spec.module === 'monitoring') && !schema) {
+                throw new Error(`Module update for ${remote.filter(spec => spec.module === 'server' || spec.module === 'monitoring').map(spec => spec.module).join(' and ')} needs the configuration schema of ${entry.name}, which neither its manifest nor its conf/Wyn.conf records. Recreate the environment with create-env.`);
+            }
+            for (const spec of remote) {
+                const stagedArtifact = staged.get(spec.module);
+                if (!stagedArtifact || !schema || !(spec.module in requiredPackageFiles))
+                    continue;
+                const warning = await verifyStagedPackage(spec.module, stagedArtifact, schema);
+                if (warning)
+                    warnings.push(warning);
+            }
             const plans = [];
             // A module may carry several local specs: plan it once, for all its targets.
             for (const module of [...new Set(parsed.map(spec => spec.module))]) {
@@ -663,7 +871,7 @@ class EnvironmentUpdater {
                     });
                     plans.push({
                         module, previous, next: { local: override.map(target => target.path).join(', ') }, local: override,
-                        entries, copies: [], removals, copiedDirectories: [], removedDirectories,
+                        entries, copies: [], removals, preserved: [], copiedDirectories: [], removedDirectories,
                     });
                     continue;
                 }
@@ -671,30 +879,59 @@ class EnvironmentUpdater {
                 const stagedArtifact = staged.get(module);
                 const copies = [];
                 const removals = [];
+                const preserved = [];
                 const copiedDirectories = [];
                 const removedDirectories = [];
                 const entries = [];
+                let configurationAssets;
+                let configurationLink;
                 for (const mapping of remoteArtifact.mappings) {
                     const destination = installationDirectory(entry.root, mapping.destination);
                     if (await exists(destination)) {
                         removals.push(destination);
                         removedDirectories.push(mapping.destination);
                     }
+                    // The Server settings the environment owns are never taken from the
+                    // archive and must survive the replacement, so carry each one that is
+                    // actually deployed across the directory swap.
+                    if (stagedArtifact && mapping.role === 'server' && workspace) {
+                        for (const name of excludedCopyNames(mapping)) {
+                            if (await exists(path.join(destination, name)))
+                                preserved.push({ directory: destination, name, source: path.join(workspace, 'preserved', module, name) });
+                        }
+                    }
                     if (stagedArtifact)
-                        copies.push({ source: path.join(stagedArtifact.expanded, mapping.source), destination });
+                        copies.push({ source: path.join(stagedArtifact.expanded, mapping.source), destination, exclude: excludedCopyNames(mapping) });
                     copiedDirectories.push(mapping.destination);
+                    // A native out-of-process service has no assembly and is declared as an
+                    // empty node: the Server loads it from that entry and supplies the rest.
+                    if (mapping.role === 'service') {
+                        if (mapping.service)
+                            entries.push({ destination: mapping.destination, assemblies: [], path: mapping.destination, role: 'service', service: mapping.service });
+                        continue;
+                    }
                     const assembly = stagedArtifact?.assemblies.get(mapping.destination) ?? knownAssembly(configured, mapping, this.platform);
                     // Plugins stay relative to the environment root; a worker entry does too,
                     // and its service keeps using the deployed destination as working directory.
-                    if (mapping.role === 'plugin' || mapping.role === 'worker') {
+                    // The Server service the Monitor starts is kept in step the same way.
+                    if (mapping.role === 'plugin' || mapping.role === 'worker' || mapping.role === 'server') {
                         const entry = { destination: mapping.destination, assemblies: mapping.assemblies, path: path.posix.join(mapping.destination, assembly) };
-                        if (mapping.role === 'worker') {
-                            entry.role = 'worker';
+                        if (mapping.role === 'worker' || mapping.role === 'server') {
+                            entry.role = mapping.role;
                             if (mapping.service)
                                 entry.service = mapping.service;
                         }
                         entries.push(entry);
                     }
+                    // The Monitor resolves its configuration from its own working directory,
+                    // so its package assets belong in the canonical `conf` and the directory
+                    // itself has to point back at it once the Monitor tree is replaced.
+                    if (mapping.role === 'monitor' && stagedArtifact) {
+                        const assets = path.join(stagedArtifact.expanded, 'conf');
+                        if ((await fs.lstat(assets).catch(() => undefined))?.isDirectory())
+                            configurationAssets = { source: assets, destination: path.join(entry.root, 'conf') };
+                        configurationLink = path.join(destination, 'conf');
+                    }
                 }
                 if (module === 'dashboard' && stagedArtifact) {
                     const contents = path.join(stagedArtifact.expanded, 'Web Contents');
@@ -704,13 +941,14 @@ class EnvironmentUpdater {
                             removals.push(destination);
                             removedDirectories.push('Web Contents');
                         }
-                        copies.push({ source: contents, destination });
+                        copies.push({ source: contents, destination, exclude: [] });
                         copiedDirectories.push('Web Contents');
                     }
                 }
                 plans.push({
                     module, previous, next: { version: remoteArtifact.version }, artifact: remoteArtifact, staged: stagedArtifact,
-                    entries, copies, removals, copiedDirectories, removedDirectories,
+                    entries, copies, removals, preserved, ...(configurationAssets ? { configurationAssets } : {}), ...(configurationLink ? { configurationLink } : {}),
+                    copiedDirectories, removedDirectories,
                 });
             }
             const changes = plans.map(plan => ({ module: plan.module, previous: plan.previous, next: plan.next, copiedDirectories: plan.copiedDirectories, removedDirectories: plan.removedDirectories }));
@@ -735,41 +973,123 @@ class EnvironmentUpdater {
                             nextDownloads.push(download);
                         else
                             nextDownloads[downloadIndex] = download;
+                        // The requirements the old artifact needed are gone with it: re-read
+                        // the ones the new package actually declares, per deployed mapping.
+                        requirements = requirements.filter(line => !line.endsWith(` (${plan.module})`));
+                        for (const mapping of plan.artifact.mappings) {
+                            if (mapping.role === 'service')
+                                continue;
+                            for (const framework of await (0, builder_1.runtimeRequirements)(path.join(plan.staged.expanded, mapping.source))) {
+                                requirements.push(`${framework.name} ${framework.version} (${plan.module})`);
+                            }
+                        }
                     }
                     delete moduleSources[plan.module];
                 }
                 if (plan.local)
                     moduleSources[plan.module] = manifestSource(plan.module, plan.local, moduleSources[plan.module]);
-                if (!installed.has(plan.module) && plan.module !== 'common' && selectedModules)
-                    selectedModules.push(plan.module);
+                // First installing a module records it the way `create-env` would: a
+                // selectable one joins the selection, a core component or an automatic
+                // dependency joins the automatically added list instead.
+                if (!installed.has(plan.module)) {
+                    if (selectable.has(plan.module)) {
+                        if (selectedModules)
+                            selectedModules.push(plan.module);
+                    }
+                    else if (autoAddedModules)
+                        autoAddedModules.push(plan.module);
+                }
             }
             if (selectedModules) {
                 const unique = [...new Set(selectedModules)].sort();
                 selectedModules.length = 0;
                 selectedModules.push(...unique);
             }
-            const nextManifest = { ...manifest, artifacts: nextArtifacts, downloads: nextDownloads };
+            if (autoAddedModules) {
+                const unique = [...new Set(autoAddedModules)].sort();
+                autoAddedModules.length = 0;
+                autoAddedModules.push(...unique);
+            }
+            const nextManifest = { ...manifest, artifacts: nextArtifacts, downloads: nextDownloads, requirements: [...new Set(requirements)] };
+            if (autoAddedModules)
+                nextManifest.autoAddedModules = autoAddedModules;
             if (Object.keys(moduleSources).length)
                 nextManifest.moduleSources = moduleSources;
             else
                 delete nextManifest.moduleSources;
             if (selectedModules)
                 nextManifest.selectedModules = selectedModules;
-            const modules = [...new Set([...entry.modules, ...plans.filter(plan => !installed.has(plan.module)).map(plan => plan.module)])].sort();
+            // The resource is recorded in place, in exactly the shape create-env writes:
+            // a second update finds the entry and refreshes it instead of adding a
+            // duplicate. The result carries the added/updated counts; the manifest keeps
+            // the durable four-field description.
+            const resources = [...(manifest.resources ?? [])];
+            const recorded = resources.findIndex(candidate => candidate.name === package_resource_1.sceneResourceName);
+            const record = { name: package_resource_1.sceneResourceName, source: resource.source, destination: resource.destination, files: resource.files };
+            if (recorded < 0)
+                resources.push(record);
+            else
+                resources[recorded] = { ...resources[recorded], ...record };
+            nextManifest.resources = resources;
+            const modules = [...new Set([...entry.modules, ...plans.filter(plan => !installed.has(plan.module) && selectable.has(plan.module)).map(plan => plan.module)])].sort();
             const localModules = Object.keys(moduleSources).sort();
             if (state === 'running')
                 warnings.push(`${entry.name} is running; restart it to load the updated modules.`);
             for (const item of skipped)
                 warnings.push(`${item.module} has a local source and was not updated from artifacts.`);
+            // The Server and Monitor packages each ship the XSD assets for a
+            // configuration schema, so replacing one of them alone leaves the
+            // environment mixing two package generations for the same configuration.
+            const runtime = plans.filter(plan => plan.module === 'server' || plan.module === 'monitoring').map(plan => plan.module).sort();
+            if (runtime.length === 1)
+                warnings.push(`Only ${runtime[0]} was refreshed; refresh ${runtime[0] === 'server' ? 'monitoring' : 'server'} in the same call to keep both packages on one configuration schema.`);
+            if (parsed.some(spec => spec.module === 'documents') && !parsed.some(spec => spec.module === 'collaboration')) {
+                warnings.push('documents was refreshed without collaboration; the smart documents plugin may expect the deployed collaboration service version, so refresh collaboration too.');
+            }
             if (!dryRun) {
                 for (const plan of plans) {
+                    // Take the environment-owned settings aside first, and drop the Monitor
+                    // configuration junction before the directory holding it: a recursive
+                    // delete must never reach the canonical `conf` the junction points at.
+                    for (const file of plan.preserved) {
+                        await fs.mkdir(path.dirname(file.source), { recursive: true });
+                        await fs.copyFile(path.join(file.directory, file.name), file.source);
+                    }
+                    if (plan.configurationLink) {
+                        const existing = await fs.lstat(plan.configurationLink).catch(() => undefined);
+                        if (existing?.isSymbolicLink())
+                            await fs.unlink(plan.configurationLink);
+                        else
+                            await fs.rm(plan.configurationLink, { recursive: true, force: true });
+                    }
                     for (const removal of plan.removals)
                         await fs.rm(removal, { recursive: true, force: true });
                     for (const copy of plan.copies)
-                        await (0, builder_1.copyTree)(copy.source, copy.destination);
+                        await (0, builder_1.copyTree)(copy.source, copy.destination, copy.exclude);
+                    for (const file of plan.preserved)
+                        await fs.copyFile(file.source, path.join(file.directory, file.name));
+                    if (plan.configurationAssets) {
+                        onProgress?.(`Refreshing Monitor configuration assets in ${path.relative(entry.root, plan.configurationAssets.destination)}`);
+                        await mergeConfigurationAssets(plan.configurationAssets.source, plan.configurationAssets.destination);
+                    }
+                    if (plan.configurationLink)
+                        await fs.symlink(path.join(entry.root, 'conf'), plan.configurationLink, 'junction');
+                }
+                // The staged resources are written with the module changes, before the
+                // manifest that records them; a failure rolls the layout back.
+                if (resourceWrites) {
+                    if (!workspace)
+                        throw new Error('Missing staging workspace for the bundled resource layout.');
+                    onProgress?.(`Laying out bundled 3D scene resources into ${package_resource_1.sceneResourceDestination}`);
+                    const applied = await (0, package_resource_1.applyBundledResource)(resourceSource, resourceDestination, resourcePlan, path.join(workspace, 'replaced-resources'));
+                    if (applied.added.length !== resourcePlan.added || applied.updated.length !== resourcePlan.updated)
+                        throw new Error('Bundled resource layout did not match its plan.');
                 }
-                onProgress?.('Writing configuration, manifest and registry record');
-                await writeAtomic(path.join(entry.root, 'conf', 'Wyn.conf'), configuration);
+                // A resource-only update (no module spec) leaves the Server configuration
+                // exactly as it is: the assets need no plugin, worker or service entry.
+                onProgress?.(plans.length ? 'Writing configuration, manifest and registry record' : 'Writing manifest and registry record');
+                if (plans.length)
+                    await writeAtomic(path.join(entry.root, 'conf', 'Wyn.conf'), configuration);
                 await writeJsonAtomic(path.join(entry.root, 'environment.lock.json'), nextManifest);
                 await this.registry.update(entries => {
                     const index = entries.findIndex(candidate => candidate.id === entry.id);
@@ -784,10 +1104,10 @@ class EnvironmentUpdater {
                         delete entries[index].localModules;
                 });
             }
-            const restartRequired = !dryRun && changes.length > 0;
+            const restartRequired = !dryRun && (changes.length > 0 || resourceWrites > 0);
             if (restartRequired)
-                onProgress?.(`${entry.name}: modules updated; restart the environment to load the change (no service was started).`);
-            return { name: entry.name, root: entry.root, dryRun, changes, skipped, restartRequired, warnings, localTargets: plans.flatMap(plan => plan.local ?? []) };
+                onProgress?.(`${entry.name}: ${changes.length ? 'modules updated' : 'bundled resources laid out'}; restart the environment to load the change (no service was started).`);
+            return { name: entry.name, root: entry.root, dryRun, changes, skipped, restartRequired, warnings, localTargets: plans.flatMap(plan => plan.local ?? []), resource };
         }
         finally {
             if (workspace)