@guanjinke/artifact-client 1.2.0 → 1.4.0

package/dist/environment/update.js

@@ -0,0 +1,644 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvironmentUpdater = void 0;
+exports.parseModuleSpecs = parseModuleSpecs;
+exports.patchEnvironmentConfiguration = patchEnvironmentConfiguration;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+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 registry_1 = require("./registry");
+const validate_1 = require("./validate");
+const process_1 = require("./process");
+/** Same parser options as the creation path, so a rewrite round-trips identically. */
+const parserOptions = { ignoreAttributes: false, parseTagValue: false, processEntities: false };
+const builderOptions = { ignoreAttributes: false, format: true, suppressEmptyNode: false };
+const windowsPath = (value) => value.replace(/\//g, '\\');
+const updatableModules = ['dashboard', 'reporting', 'sheets', 'analysis', 'common'];
+const installationDirectory = (root, destination) => path.join(root, ...destination.split('/'));
+function validateUpdatableModule(module) {
+    if (updatableModules.includes(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 === 'documents')
+        throw new Error('Module documents cannot be updated: embedded Documents execution is not supported.');
+    throw new Error(`Unsupported module "${module}": updateable modules are dashboard, reporting, sheets, analysis and common.`);
+}
+/** `all` is the only allowed pseudo-module: every configured module from remote. */
+const allModules = 'all';
+function parseModuleSpec(value) {
+    const equals = value.indexOf('=');
+    if (equals >= 0) {
+        const module = value.slice(0, equals).trim().toLowerCase();
+        const localPath = value.slice(equals + 1).trim();
+        if (!module)
+            throw new Error(`Invalid module spec "${value}": missing module name.`);
+        if (module === allModules)
+            throw new Error(`Invalid module spec "${value}": all selects every configured module from remote and cannot point at a local source.`);
+        // The module token itself may not carry a pinned version: `=` and `:` select
+        // different sources. A Windows drive letter inside the path is not that.
+        if (module.includes(':'))
+            throw new Error(`Invalid module spec "${value}": a local source (=) cannot also pin a version (:).`);
+        if (!localPath)
+            throw new Error(`Invalid module spec "${value}": missing local DLL path.`);
+        return { module, localPath };
+    }
+    const colon = value.indexOf(':');
+    if (colon >= 0) {
+        const module = value.slice(0, colon).trim().toLowerCase();
+        const version = value.slice(colon + 1).trim();
+        if (!module)
+            throw new Error(`Invalid module spec "${value}": missing module name.`);
+        if (module === allModules)
+            throw new Error(`Invalid module spec "${value}": all selects every configured module from remote and cannot pin a version.`);
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(version))
+            throw new Error(`Invalid module spec "${value}": invalid pinned version.`);
+        return { module, version };
+    }
+    const module = value.trim().toLowerCase();
+    if (!module)
+        throw new Error(`Invalid module spec "${value}": missing module name.`);
+    if (module === allModules)
+        return { module: allModules };
+    return { module };
+}
+/** Record one parsed spec, enforcing "all alone" and duplicate rules. */
+function pushSpec(specs, seen, spec) {
+    if (spec.module === allModules) {
+        if (seen.has(allModules))
+            throw new Error('Duplicate module in one update: all.');
+        if (seen.size > 0)
+            throw new Error('Module spec all cannot be combined with individual modules.');
+    }
+    else {
+        validateUpdatableModule(spec.module);
+        if (seen.has(allModules))
+            throw new Error('Module spec all cannot be combined with individual modules.');
+        if (seen.has(spec.module))
+            throw new Error(`Duplicate module in one update: ${spec.module}.`);
+    }
+    seen.add(spec.module);
+    specs.push(spec);
+}
+/**
+ * Parse `--modules` values into module specs.
+ *
+ * Values that carry a local source (`module=path`) are split on commas only, so
+ * a Windows path may contain spaces; every other value accepts space- and
+ * comma-separated specs, which is how the CLI passes `--modules a b,c`.
+ * `all` selects every configured module from remote and must be used alone.
+ */
+function parseModuleSpecs(values) {
+    if (!Array.isArray(values))
+        throw new Error('Module specs must be an array of strings.');
+    const specs = [];
+    const seen = new Set();
+    for (const value of values) {
+        const text = String(value ?? '');
+        for (const fragment of text.includes('=') ? text.split(',') : text.split(/[\s,]+/)) {
+            const entry = fragment.trim();
+            if (!entry)
+                continue;
+            pushSpec(specs, seen, parseModuleSpec(entry));
+        }
+    }
+    return specs;
+}
+function normalizeModuleSpecs(values) {
+    if (!Array.isArray(values))
+        throw new Error('Module specs must be an array.');
+    const specs = [];
+    const seen = new Set();
+    const push = (spec) => pushSpec(specs, seen, spec);
+    for (const value of values) {
+        if (typeof value === 'string') {
+            for (const spec of parseModuleSpecs([value]))
+                push(spec);
+            continue;
+        }
+        if (!value || typeof value !== 'object')
+            throw new Error('Invalid module spec.');
+        const module = typeof value.module === 'string' ? value.module.trim().toLowerCase() : '';
+        const version = value.version === undefined ? undefined : String(value.version);
+        const localPath = value.localPath === undefined ? undefined : String(value.localPath);
+        if (!module)
+            throw new Error('Invalid module spec: missing module name.');
+        if (module === allModules) {
+            if (version !== undefined || localPath !== undefined)
+                throw new Error('Module spec all cannot pin a version or point at a local source.');
+            push({ module: allModules });
+            continue;
+        }
+        if (version !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(version))
+            throw new Error(`Invalid version for module ${module}.`);
+        if (version !== undefined && localPath !== undefined)
+            throw new Error(`Module ${module} cannot combine a local path (=) with a pinned version (:).`);
+        if (version === undefined && localPath === undefined) {
+            push({ module });
+            continue;
+        }
+        push({ module, ...(version !== undefined ? { version } : {}), ...(localPath !== undefined ? { localPath } : {}) });
+    }
+    return specs;
+}
+/**
+ * Rewrite the `<Server><Plugins>` list of a Wyn configuration document.
+ *
+ * The document is parsed with the creation path's parser options, only the
+ * `sys:string` plugin list is mutated, and the result is rebuilt with the same
+ * builder options and re-validated before it is returned. Dashboard stays the
+ * first entry; unknown existing entries keep their order.
+ */
+function patchEnvironmentConfiguration(xml, entries) {
+    if (typeof xml !== 'string' || /<!DOCTYPE|<!ENTITY/i.test(xml) || fast_xml_parser_1.XMLValidator.validate(xml) !== true)
+        throw new Error('Invalid environment configuration.');
+    const document = new fast_xml_parser_1.XMLParser(parserOptions).parse(xml);
+    const server = document?.SystemConfig?.Services?.Server;
+    if (!server || typeof server !== 'object' || Array.isArray(server))
+        throw new Error('Environment configuration has no Server service.');
+    const plugins = server.Plugins ?? {};
+    if (typeof plugins !== 'object' || Array.isArray(plugins))
+        throw new Error('Invalid environment configuration.');
+    const raw = plugins['sys:string'];
+    const list = raw === undefined ? [] : Array.isArray(raw) ? [...raw] : [raw];
+    if (list.some(value => typeof value !== 'string'))
+        throw new Error('Invalid environment configuration.');
+    const strings = list.map(value => value.trim());
+    const used = new Set();
+    const appended = [];
+    for (const entry of entries) {
+        const prefix = windowsPath(entry.destination).toLowerCase() + '\\';
+        const assemblies = new Set(entry.assemblies.map(name => name.toLowerCase()));
+        const index = strings.findIndex((value, candidate) => {
+            if (used.has(candidate))
+                return false;
+            const folded = windowsPath(value).toLowerCase();
+            return folded.startsWith(prefix) || assemblies.has(path.win32.basename(folded));
+        });
+        if (index < 0)
+            appended.push(windowsPath(entry.path));
+        else {
+            used.add(index);
+            strings[index] = windowsPath(entry.path);
+        }
+    }
+    const combined = [...strings, ...appended];
+    // Keep Dashboard first even when it is a local build path rather than a deployed one.
+    const dashboard = combined.findIndex(value => {
+        const folded = windowsPath(value).toLowerCase();
+        return folded.startsWith('plugins\\dashboard\\') || path.win32.basename(folded) === 'wyn.dashboards.plugin.dll';
+    });
+    if (dashboard > 0)
+        combined.unshift(combined.splice(dashboard, 1)[0]);
+    plugins['sys:string'] = combined;
+    server.Plugins = plugins;
+    const output = new fast_xml_parser_1.XMLBuilder(builderOptions).build(document);
+    if (fast_xml_parser_1.XMLValidator.validate(output) !== true)
+        throw new Error('Invalid environment configuration.');
+    return output;
+}
+async function exists(target) {
+    try {
+        await fs.lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function readManifest(root) {
+    const file = path.join(root, 'environment.lock.json');
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error('Environment manifest is not a regular file.');
+    let document;
+    try {
+        document = JSON.parse(await fs.readFile(file, 'utf8'));
+    }
+    catch {
+        throw new Error('Environment manifest is unreadable.');
+    }
+    if (!document || typeof document !== 'object' || Array.isArray(document))
+        throw new Error('Environment manifest is unreadable.');
+    const manifest = document;
+    for (const field of ['artifacts', 'downloads']) {
+        const value = manifest[field];
+        if (value !== undefined && (!Array.isArray(value) || value.some(item => !item || typeof item !== 'object')))
+            throw new Error('Environment manifest is unreadable.');
+    }
+    if (manifest.selectedModules !== undefined && (!Array.isArray(manifest.selectedModules) || manifest.selectedModules.some(module => typeof module !== '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.');
+    return manifest;
+}
+/** Write JSON (or any text) through `<file>.afm-tmp` and an atomic rename. */
+async function writeAtomic(file, content) {
+    const temporary = `${file}.afm-tmp`;
+    await fs.writeFile(temporary, content, 'utf8');
+    await fs.rename(temporary, file);
+}
+const writeJsonAtomic = (file, value) => writeAtomic(file, JSON.stringify(value, null, 2) + '\n');
+/**
+ * Resolve one remote spec against the record's major and the module's exact
+ * artifact name; version `undefined` means "latest for the record's major".
+ */
+async function resolveRemoteArtifact(client, entry, spec) {
+    const module = spec.module;
+    const source = catalog_1.catalog[module];
+    let version;
+    let files;
+    try {
+        version = spec.version ?? (await client.getLatestVersion(source.plugin, entry.major)).version;
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(version))
+            throw new Error('Invalid resolved version');
+        files = await client.listArtifacts(source.plugin, version);
+    }
+    catch {
+        throw new Error(`Unable to resolve artifacts for ${source.plugin}/${spec.version ?? entry.major}.`);
+    }
+    const name = source.filename(version, entry.edition);
+    const candidates = files.filter(file => file.name === name);
+    if (candidates.length !== 1)
+        throw new Error(`${source.plugin}/${version}: expected exactly one ${name}, found ${candidates.length}.`);
+    const remotePath = candidates[0].path;
+    if (!remotePath || /[?:\\\x00-\x1f]/.test(remotePath) || remotePath.startsWith('/') || remotePath.split('/').includes('..'))
+        throw new Error(`${source.plugin}/${version}: invalid artifact path.`);
+    return { module, plugin: source.plugin, version, name, path: remotePath, mappings: source.mappings.map(mapping => ({ ...mapping, assemblies: [...mapping.assemblies] })) };
+}
+/** Download, hash, extract and verify one resolved artifact inside the staging workspace. */
+async function stageRemoteArtifact(client, artifact, workspace, onProgress) {
+    const label = `[${artifact.module}] ${artifact.plugin}/${artifact.version}/${artifact.name}`;
+    const download = path.join(workspace, 'download', artifact.module);
+    const expanded = path.join(workspace, `expanded-${artifact.module}`);
+    try {
+        await fs.mkdir(download, { recursive: true });
+        onProgress?.(`${label}: Downloading`);
+        await client.downloadArtifact(artifact.plugin, artifact.version, artifact.name, download);
+        const archive = path.join(download, artifact.name);
+        await (0, builder_1.regularFile)(archive);
+        onProgress?.(`${label}: Download complete; calculating SHA256`);
+        const sha256 = await (0, builder_1.hashFile)(archive);
+        onProgress?.(`${label}: Extracting and validating ZIP`);
+        await (0, archive_1.extractArchive)(archive, expanded);
+        const assemblies = new Map();
+        for (const mapping of artifact.mappings) {
+            const source = path.join(expanded, mapping.source);
+            if (!(await fs.lstat(source)).isDirectory())
+                throw new Error('Required source directory missing.');
+            const present = [];
+            for (const name of mapping.assemblies) {
+                try {
+                    await (0, builder_1.regularFile)(path.join(source, name));
+                    present.push(name);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+            if (present.length !== 1)
+                throw new Error(`Expected one runtime assembly in ${mapping.destination || 'root'}.`);
+            assemblies.set(mapping.destination, present[0]);
+        }
+        onProgress?.(`${label}: Archive and layout checks complete`);
+        return { ...artifact, sha256, expanded, assemblies };
+    }
+    catch (error) {
+        throw new Error(`Module update failed for ${artifact.plugin}/${artifact.version}/${artifact.name} (download, archive or layout): ${error.message}`);
+    }
+}
+/** Resolve and validate a local plugin source for one module. */
+async function resolveLocalSource(entry, module, mappings, input) {
+    const plugins = mappings.filter(mapping => mapping.role === 'plugin');
+    if (plugins.length !== 1)
+        throw new Error(`Local sources are not supported for module ${module}: it deploys ${plugins.length} plugin directories (${plugins.map(mapping => mapping.destination).join(', ')}). Use a remote update instead.`);
+    const mapping = plugins[0];
+    const target = path.resolve(input);
+    const stat = await fs.lstat(target).catch((error) => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (!stat)
+        throw new Error(`Local source not found: ${target}.`);
+    let dll;
+    if (stat.isSymbolicLink())
+        throw new Error(`Local source must be a regular file or directory: ${target}.`);
+    if (stat.isFile()) {
+        if (path.extname(target).toLowerCase() !== '.dll')
+            throw new Error(`Local source must be a .dll file: ${target}.`);
+        dll = target;
+    }
+    else if (stat.isDirectory()) {
+        const found = [];
+        for (const assembly of mapping.assemblies) {
+            const candidate = path.join(target, assembly);
+            const candidateStat = await fs.lstat(candidate).catch((error) => { if (error.code === 'ENOENT')
+                return undefined; throw error; });
+            if (candidateStat?.isFile() && !candidateStat.isSymbolicLink())
+                found.push(candidate);
+        }
+        if (found.length !== 1)
+            throw new Error(`Local source directory ${target} must contain exactly one of ${mapping.assemblies.join(', ')}; found ${found.length}.`);
+        dll = found[0];
+    }
+    else
+        throw new Error(`Local source must be a regular .dll file or a directory: ${target}.`);
+    const deployed = installationDirectory(entry.root, mapping.destination);
+    const relative = path.relative(deployed.toLowerCase(), dll.toLowerCase());
+    if (relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative))
+        throw new Error(`Local source ${dll} is inside the deployed plugin directory ${deployed}; point at the developer build output outside the environment.`);
+    return { dll, pluginDirectories: [mapping.destination] };
+}
+/**
+ * Update selected modules of a registered environment.
+ *
+ * Remote specs replace the deployed module directories with a freshly verified
+ * artifact; local specs copy nothing, delete the deployed plugin directory and
+ * point the Server configuration at the absolute local DLL so the developer
+ * build is loaded directly. Files are staged in a sibling temporary workspace
+ * that is always removed, and JSON files are written through `<file>.afm-tmp`.
+ */
+class EnvironmentUpdater {
+    dependencies;
+    registry;
+    processes;
+    platform;
+    onProgress;
+    constructor(dependencies = {}) {
+        this.dependencies = dependencies;
+        this.registry = dependencies.registry ?? new registry_1.EnvironmentRegistry();
+        this.processes = dependencies.processes ?? new process_1.WindowsProcessBackend();
+        this.platform = dependencies.platform ?? process.platform;
+        this.onProgress = dependencies.onProgress;
+    }
+    async update(name, specs, clientFactory, options = {}) {
+        const dryRun = options.dryRun === true;
+        const onProgress = options.onProgress ?? this.onProgress;
+        if (!dryRun && this.platform !== 'win32')
+            throw new Error('Environment execution is Windows-only. Use dry-run on other platforms.');
+        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.');
+        const entry = await this.registry.get(name);
+        onProgress?.(`Validating environment ${entry.name} at ${entry.root}`);
+        await (0, validate_1.validateEnvironmentRoot)(entry, this.registry.directory);
+        await (0, validate_1.validateEnvironmentOwnership)(entry, this.registry.directory);
+        await (0, validate_1.validateEnvironmentTree)(entry.root);
+        const manifest = await readManifest(entry.root);
+        const artifacts = [...(manifest.artifacts ?? [])];
+        const skipped = [];
+        if (parsed.some(spec => spec.module === 'all')) {
+            // `all` means every configured module from remote; modules that already
+            // point at a local developer build are left exactly as they are.
+            const localModules = new Set([...Object.keys(manifest.moduleSources ?? {}), ...(entry.localModules ?? [])]);
+            const configured = [...new Set(artifacts.map(artifact => artifact.module))].filter(module => updatableModules.includes(module)).sort();
+            for (const module of configured)
+                if (localModules.has(module))
+                    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)'}.`);
+            parsed = selected.map(module => ({ module }));
+            onProgress?.(`Updating all configured modules from remote: ${selected.join(', ')}${skipped.length ? ` (skipping local: ${skipped.map(item => item.module).join(', ')})` : ''}`);
+        }
+        const localOverrides = new Map();
+        for (const spec of parsed) {
+            if (spec.module === 'sheets' && entry.edition !== 'en')
+                throw new Error(`Module sheets requires an EN edition environment; ${entry.name} is ${entry.edition}.`);
+            if (spec.localPath === undefined)
+                continue;
+            localOverrides.set(spec.module, await resolveLocalSource(entry, spec.module, catalog_1.catalog[spec.module].mappings, spec.localPath));
+        }
+        const remote = parsed.filter(spec => spec.localPath === undefined);
+        const state = await (0, validate_1.observeRuntimeState)(entry, this.processes);
+        if (remote.length && state !== 'ready' && state !== 'stopped')
+            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.`);
+        const downloads = [...(manifest.downloads ?? [])];
+        const selectedModules = manifest.selectedModules === undefined ? undefined : [...manifest.selectedModules];
+        const moduleSources = { ...(manifest.moduleSources ?? {}) };
+        const installed = new Set(artifacts.map(artifact => artifact.module));
+        const workspace = remote.length && !dryRun ? await fs.mkdtemp(path.join(path.dirname(entry.root), '.afm-env-')) : undefined;
+        const warnings = [];
+        try {
+            const resolved = new Map();
+            const staged = new Map();
+            if (remote.length) {
+                const client = clientFactory();
+                for (const spec of remote) {
+                    onProgress?.(`Resolving ${catalog_1.catalog[spec.module].plugin}`);
+                    resolved.set(spec.module, await resolveRemoteArtifact(client, entry, spec));
+                }
+                if (!dryRun)
+                    for (const spec of remote)
+                        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');
+            const plans = [];
+            for (const spec of parsed) {
+                const module = spec.module;
+                const artifact = artifacts.find(candidate => candidate.module === module);
+                const previous = moduleSources[module] ? { local: moduleSources[module].path } : { version: artifact?.version };
+                const pluginMappings = catalog_1.catalog[module].mappings.filter(mapping => mapping.role === 'plugin');
+                const override = localOverrides.get(module);
+                if (override) {
+                    const removals = [];
+                    const removedDirectories = [];
+                    for (const mapping of pluginMappings) {
+                        const destination = installationDirectory(entry.root, mapping.destination);
+                        if (!await exists(destination))
+                            continue;
+                        removals.push(destination);
+                        removedDirectories.push(mapping.destination);
+                    }
+                    plans.push({
+                        module, previous, next: { local: override.dll }, local: override,
+                        entries: pluginMappings.map(mapping => ({ destination: mapping.destination, assemblies: mapping.assemblies, path: override.dll })),
+                        copies: [], removals, copiedDirectories: [], removedDirectories,
+                    });
+                    continue;
+                }
+                const remoteArtifact = resolved.get(module);
+                const stagedArtifact = staged.get(module);
+                const copies = [];
+                const removals = [];
+                const copiedDirectories = [];
+                const removedDirectories = [];
+                const entries = [];
+                for (const mapping of remoteArtifact.mappings) {
+                    const destination = installationDirectory(entry.root, mapping.destination);
+                    if (await exists(destination)) {
+                        removals.push(destination);
+                        removedDirectories.push(mapping.destination);
+                    }
+                    if (stagedArtifact)
+                        copies.push({ source: path.join(stagedArtifact.expanded, mapping.source), destination });
+                    copiedDirectories.push(mapping.destination);
+                    const assembly = stagedArtifact?.assemblies.get(mapping.destination) ?? knownAssembly(configured, mapping);
+                    if (mapping.role === 'plugin')
+                        entries.push({ destination: mapping.destination, assemblies: mapping.assemblies, path: path.posix.join(mapping.destination, assembly) });
+                }
+                if (module === 'dashboard' && stagedArtifact) {
+                    const contents = path.join(stagedArtifact.expanded, 'Web Contents');
+                    if ((await fs.lstat(contents).catch(() => undefined))?.isDirectory()) {
+                        const destination = path.join(entry.root, 'Web Contents');
+                        if (await exists(destination)) {
+                            removals.push(destination);
+                            removedDirectories.push('Web Contents');
+                        }
+                        copies.push({ source: contents, destination });
+                        copiedDirectories.push('Web Contents');
+                    }
+                }
+                plans.push({
+                    module, previous, next: { version: remoteArtifact.version }, artifact: remoteArtifact, staged: stagedArtifact,
+                    entries, copies, removals, copiedDirectories, removedDirectories,
+                });
+            }
+            const changes = plans.map(plan => ({ module: plan.module, previous: plan.previous, next: plan.next, copiedDirectories: plan.copiedDirectories, removedDirectories: plan.removedDirectories }));
+            const configuration = patchEnvironmentConfiguration(configured, plans.flatMap(plan => plan.entries));
+            const nextArtifacts = [...artifacts];
+            const nextDownloads = [...downloads];
+            for (const plan of plans) {
+                if (plan.artifact) {
+                    const replacement = {
+                        module: plan.module, plugin: plan.artifact.plugin, version: plan.artifact.version, name: plan.artifact.name, path: plan.artifact.path,
+                        mappings: catalog_1.catalog[plan.module].mappings.map(mapping => ({ ...mapping, assemblies: [...mapping.assemblies] })),
+                    };
+                    const index = nextArtifacts.findIndex(candidate => candidate.module === plan.module);
+                    if (index < 0)
+                        nextArtifacts.push(replacement);
+                    else
+                        nextArtifacts[index] = { ...nextArtifacts[index], ...replacement };
+                    if (plan.staged) {
+                        const download = { plugin: plan.artifact.plugin, version: plan.artifact.version, name: plan.artifact.name, sha256: plan.staged.sha256 };
+                        const downloadIndex = nextDownloads.findIndex(candidate => candidate.plugin === plan.artifact.plugin);
+                        if (downloadIndex < 0)
+                            nextDownloads.push(download);
+                        else
+                            nextDownloads[downloadIndex] = download;
+                    }
+                    delete moduleSources[plan.module];
+                }
+                if (plan.local)
+                    moduleSources[plan.module] = { type: 'local', path: plan.local.dll, pluginDirectories: plan.local.pluginDirectories };
+                if (!installed.has(plan.module) && plan.module !== 'common' && selectedModules)
+                    selectedModules.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 (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();
+            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.`);
+            if (!dryRun) {
+                for (const plan of plans) {
+                    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);
+                }
+                onProgress?.('Writing configuration, manifest and registry record');
+                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);
+                    if (index < 0)
+                        throw new Error('Environment record disappeared during update.');
+                    if (entries[index].root !== entry.root)
+                        throw new Error('Environment changed during update.');
+                    entries[index].modules = modules;
+                    if (localModules.length)
+                        entries[index].localModules = localModules;
+                    else
+                        delete entries[index].localModules;
+                });
+            }
+            const restartRequired = !dryRun && changes.length > 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 };
+        }
+        finally {
+            if (workspace)
+                await fs.rm(workspace, { recursive: true, force: true });
+        }
+    }
+}
+exports.EnvironmentUpdater = EnvironmentUpdater;
+/** Best-effort preview assembly for dry-run, where nothing can be extracted. */
+function knownAssembly(xml, mapping) {
+    try {
+        const document = new fast_xml_parser_1.XMLParser(parserOptions).parse(xml);
+        const raw = document?.SystemConfig?.Services?.Server?.Plugins?.['sys:string'];
+        const list = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw];
+        const prefix = windowsPath(mapping.destination).toLowerCase() + '\\';
+        for (const value of list) {
+            if (typeof value !== 'string')
+                continue;
+            const folded = windowsPath(value).toLowerCase();
+            if (!folded.startsWith(prefix))
+                continue;
+            const name = path.win32.basename(folded);
+            const match = mapping.assemblies.find(assembly => assembly.toLowerCase() === name);
+            if (match)
+                return match;
+        }
+    }
+    catch { /* Fall through to the first known assembly name. */ }
+    return mapping.assemblies[0];
+}
+//# sourceMappingURL=update.js.map