@guanjinke/artifact-client 1.3.0 → 1.5.0

package/dist/environment/update.js

@@ -0,0 +1,810 @@
+"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 token = value.slice(0, equals).trim();
+        const hash = token.indexOf('#');
+        const module = (hash >= 0 ? token.slice(0, hash) : token).trim().toLowerCase();
+        const assembly = hash >= 0 ? token.slice(hash + 1).trim() : undefined;
+        if (!module)
+            throw new Error(`Invalid module spec "${value}": missing module name.`);
+        if (assembly !== undefined && !assembly)
+            throw new Error(`Invalid module spec "${value}": missing assembly name after #.`);
+        if (assembly !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(assembly))
+            throw new Error(`Invalid module spec "${value}": invalid assembly file 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 (:).`);
+        const localPath = value.slice(equals + 1).trim();
+        if (!localPath)
+            throw new Error(`Invalid module spec "${value}": missing local DLL path.`);
+        return { module, localPath, ...(assembly !== undefined ? { assembly } : {}) };
+    }
+    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.
+ *
+ * A module may be named several times only when every one of its specs is a
+ * local source: each local spec resolves to one or more targets, and the update
+ * refuses a target that is selected twice. A remote spec replaces the whole
+ * module, so it may never share a module with another spec.
+ */
+function pushSpec(specs, seen, spec) {
+    const kind = spec.localPath === undefined ? 'remote' : 'local';
+    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.');
+        const previous = seen.get(spec.module);
+        if (previous !== undefined && (previous === 'remote' || kind === 'remote'))
+            throw new Error(`Duplicate module in one update: ${spec.module}.`);
+    }
+    seen.set(spec.module, kind);
+    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 Map();
+    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 Map();
+    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);
+        const assembly = value.assembly === undefined ? undefined : String(value.assembly);
+        if (!module)
+            throw new Error('Invalid module spec: missing module name.');
+        if (module === allModules) {
+            if (version !== undefined || localPath !== undefined || assembly !== 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 (assembly !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(assembly))
+            throw new Error(`Invalid assembly file name for module ${module}.`);
+        if (assembly !== undefined && localPath === undefined)
+            throw new Error(`Module ${module} names an assembly (#) without a local path (=).`);
+        if (version === undefined && localPath === undefined) {
+            push({ module });
+            continue;
+        }
+        push({ module, ...(version !== undefined ? { version } : {}), ...(localPath !== undefined ? { localPath } : {}), ...(assembly !== undefined ? { assembly } : {}) });
+    }
+    return specs;
+}
+/** Read one `<sys:string>` list, accepting a single string instead of an array. */
+function stringList(raw) {
+    const list = raw === undefined ? [] : Array.isArray(raw) ? [...raw] : [raw];
+    if (list.some(value => typeof value !== 'string'))
+        throw new Error('Invalid environment configuration.');
+    return list;
+}
+/** Replace or append one `<sys:string>` path list, matching by destination or assembly name. */
+function rewritePathList(values, entries) {
+    const strings = values.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);
+        }
+    }
+    return [...strings, ...appended];
+}
+/**
+ * Rewrite the `<Server><Plugins>`, `<Server><PluginWorkers>` and worker service
+ * entries of a Wyn configuration document.
+ *
+ * The document is parsed with the creation path's parser options, only the
+ * `sys:string` path lists and the matching worker service nodes are mutated, and
+ * the result is rebuilt with the same builder options and re-validated before it
+ * 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.
+ */
+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 pluginEntries = entries.filter(entry => entry.role !== 'worker');
+    if (server.Plugins !== undefined || pluginEntries.length) {
+        const plugins = server.Plugins === undefined || server.Plugins === '' ? {} : server.Plugins;
+        if (typeof plugins !== 'object' || Array.isArray(plugins))
+            throw new Error('Invalid environment configuration.');
+        const combined = rewritePathList(stringList(plugins['sys:string']), pluginEntries);
+        // 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 workers = entries.filter(entry => entry.role === 'worker');
+    if (workers.length) {
+        const pluginWorkers = server.PluginWorkers === undefined || server.PluginWorkers === '' ? {} : server.PluginWorkers;
+        if (typeof pluginWorkers !== 'object' || Array.isArray(pluginWorkers))
+            throw new Error('Invalid environment configuration.');
+        pluginWorkers['sys:string'] = rewritePathList(stringList(pluginWorkers['sys:string']), workers);
+        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))
+                continue;
+            const node = service;
+            // The worker 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(path.win32.dirname(entry.path));
+            node.Assembly = path.win32.basename(entry.path);
+        }
+    }
+    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.');
+    for (const source of Object.values(manifest.moduleSources ?? {})) {
+        if (!source || typeof source !== 'object' || Array.isArray(source) || source.type !== 'local' || typeof source.path !== 'string' || !Array.isArray(source.pluginDirectories) || source.pluginDirectories.some(directory => typeof directory !== 'string'))
+            throw new Error('Environment manifest is unreadable.');
+        if (source.targets !== undefined && (!Array.isArray(source.targets) || source.targets.some(target => !target || typeof target !== 'object' || target.kind !== 'plugin' && target.kind !== 'worker' || typeof target.destination !== 'string' || typeof target.assembly !== 'string' || typeof target.path !== 'string')))
+            throw new Error('Environment manifest is unreadable.');
+    }
+    return manifest;
+}
+/**
+ * Normalize a recorded module source into targets.
+ *
+ * The 1.4.0 shape (`path` plus `pluginDirectories`) is still written whenever it
+ * describes the state exactly; it always meant one plugin target per recorded
+ * directory.
+ */
+function localTargetsOf(module, source) {
+    if (!source)
+        return [];
+    if (Array.isArray(source.targets) && source.targets.length)
+        return source.targets.map(target => ({ module, kind: target.kind, destination: target.destination, assembly: target.assembly, path: target.path }));
+    return (source.pluginDirectories ?? []).map(destination => ({ module, kind: 'plugin', destination, assembly: path.win32.basename(source.path), path: source.path }));
+}
+/** Record the local targets of one module, keeping earlier targets of that module. */
+function manifestSource(module, targets, previous) {
+    const overridden = new Set(targets.map(target => target.destination.toLowerCase()));
+    const merged = [...localTargetsOf(module, previous).filter(target => !overridden.has(target.destination.toLowerCase())), ...targets];
+    const source = { type: 'local', path: merged[0].path, pluginDirectories: merged.filter(target => target.kind === 'plugin').map(target => target.destination) };
+    if (merged.length > 1 || merged[0].kind !== 'plugin')
+        source.targets = merged.map(({ kind, destination, assembly, path: file }) => ({ kind, destination, assembly, path: file }));
+    return source;
+}
+/** 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}`);
+    }
+}
+/** 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))];
+const lstatOrUndefined = (target) => fs.lstat(target).catch((error) => { if (error.code === 'ENOENT')
+    return undefined; throw error; });
+/** Locate the single mapping of `module` whose known assemblies include `assembly`. */
+function mappingForAssembly(module, assembly) {
+    const wanted = assembly.toLowerCase();
+    const matches = localMappings(module).filter(mapping => mapping.assemblies.some(name => name.toLowerCase() === wanted));
+    if (matches.length !== 1)
+        throw new Error(`Local target ${assembly} is not one assembly of module ${module}. Expected one of ${expectedAssemblies(module).join(', ')}.`);
+    return { mapping: matches[0], assembly: matches[0].assemblies.find(name => name.toLowerCase() === wanted) };
+}
+/**
+ * Resolve one local source into the module targets it overrides.
+ *
+ * A DLL selects the mapping whose assembly file name it matches. A directory
+ * selects every mapping that holds exactly one of its assemblies, so a partial
+ * developer build only overrides what it really contains; the other mappings are
+ * reported as inactive and stay deployed. `module#<assembly>=` names the target
+ * explicitly, for a build whose file name matches no assembly at all.
+ */
+async function resolveLocalSource(entry, module, assembly, input) {
+    const mappings = localMappings(module);
+    const source = path.resolve(input);
+    const stat = await lstatOrUndefined(source);
+    if (!stat)
+        throw new Error(`Local source not found: ${source}.`);
+    if (stat.isSymbolicLink())
+        throw new Error(`Local source must be a regular file or directory: ${source}.`);
+    const selected = [];
+    const inactive = [];
+    if (stat.isFile()) {
+        if (path.extname(source).toLowerCase() !== '.dll')
+            throw new Error(`Local source must be a .dll file: ${source}.`);
+        if (assembly === undefined) {
+            const name = path.win32.basename(source).toLowerCase();
+            const matches = mappings.filter(mapping => mapping.assemblies.some(known => known.toLowerCase() === name));
+            if (matches.length !== 1)
+                throw new Error(`Local source ${source} matches ${matches.length} targets of module ${module}. Expected one of ${expectedAssemblies(module).join(', ')}; select one explicitly with ${module}#<assembly>=<path>.`);
+            selected.push({ mapping: matches[0], assembly: matches[0].assemblies.find(known => known.toLowerCase() === name), path: source });
+            inactive.push(...mappings.filter(mapping => mapping !== matches[0]).map(mapping => mapping.destination));
+        }
+        else {
+            const named = mappingForAssembly(module, assembly);
+            // The explicit form exists for a build whose file name matches no assembly;
+            // a file that is another target's assembly is still a mistake.
+            const basename = path.win32.basename(source);
+            const conflicts = mappings.filter(mapping => mapping !== named.mapping && mapping.assemblies.some(known => known.toLowerCase() === basename.toLowerCase()));
+            if (conflicts.length)
+                throw new Error(`Local source ${source} is an assembly of ${conflicts.map(mapping => mapping.destination).join(', ')}, not of ${named.mapping.destination}: ${module}#${assembly}= selects ${named.mapping.destination}.`);
+            selected.push({ mapping: named.mapping, assembly: named.assembly, path: source });
+            inactive.push(...mappings.filter(mapping => mapping !== named.mapping).map(mapping => mapping.destination));
+        }
+    }
+    else if (stat.isDirectory()) {
+        const named = assembly === undefined ? undefined : mappingForAssembly(module, assembly);
+        for (const mapping of named ? [named.mapping] : mappings) {
+            const present = [];
+            for (const name of named ? [named.assembly] : mapping.assemblies) {
+                const candidate = path.join(source, name);
+                const candidateStat = await lstatOrUndefined(candidate);
+                if (candidateStat?.isFile() && !candidateStat.isSymbolicLink())
+                    present.push({ assembly: name, path: candidate });
+            }
+            if (present.length === 1)
+                selected.push({ mapping, ...present[0] });
+            else
+                inactive.push(mapping.destination);
+        }
+        // An explicit selection leaves every other mapping of the module deployed.
+        if (named)
+            inactive.push(...mappings.filter(mapping => mapping !== named.mapping).map(mapping => mapping.destination));
+        if (!selected.length) {
+            if (named)
+                throw new Error(`Local source directory ${source} does not contain ${named.assembly}.`);
+            throw new Error(`Local source directory ${source} must contain exactly one of ${expectedAssemblies(module).join(', ')} for module ${module}; select one explicitly with ${module}#<assembly>=<path>.`);
+        }
+    }
+    else
+        throw new Error(`Local source must be a regular .dll file or a directory: ${source}.`);
+    const targets = selected.map(item => {
+        const deployed = installationDirectory(entry.root, item.mapping.destination);
+        const relative = path.relative(deployed.toLowerCase(), item.path.toLowerCase());
+        if (relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative))
+            throw new Error(`Local source ${item.path} is inside the deployed ${item.mapping.role === 'worker' ? 'worker' : 'plugin'} directory ${deployed}; point at the developer build output outside the environment.`);
+        const target = { module, kind: item.mapping.role, destination: item.mapping.destination, assembly: item.assembly, path: item.path };
+        if (item.mapping.service)
+            target.service = item.mapping.service;
+        return target;
+    });
+    return { targets, inactive, source };
+}
+/**
+ * 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();
+        const selectedTargets = new Set();
+        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;
+            const resolution = await resolveLocalSource(entry, spec.module, spec.assembly, spec.localPath);
+            for (const destination of resolution.inactive)
+                onProgress?.(`${spec.module}: ${destination} stays deployed (not selected by ${resolution.source})`);
+            const targets = localOverrides.get(spec.module) ?? [];
+            for (const target of resolution.targets) {
+                if (selectedTargets.has(target.destination.toLowerCase()))
+                    throw new Error(`Local target ${target.assembly} of module ${target.module} is selected twice in one update; give one spec per assembly.`);
+                selectedTargets.add(target.destination.toLowerCase());
+                targets.push(target);
+            }
+            localOverrides.set(spec.module, targets);
+        }
+        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 = [];
+            // 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))]) {
+                const artifact = artifacts.find(candidate => candidate.module === module);
+                const previous = moduleSources[module] ? { local: moduleSources[module].path } : { version: artifact?.version };
+                const override = localOverrides.get(module);
+                if (override) {
+                    const removals = [];
+                    const removedDirectories = [];
+                    for (const target of override) {
+                        const destination = installationDirectory(entry.root, target.destination);
+                        if (!await exists(destination))
+                            continue;
+                        removals.push(destination);
+                        removedDirectories.push(target.destination);
+                    }
+                    const entries = override.map(target => {
+                        const entry = { destination: target.destination, assemblies: [target.assembly], path: target.path };
+                        if (target.kind === 'worker') {
+                            entry.role = 'worker';
+                            if (target.service)
+                                entry.service = target.service;
+                        }
+                        return entry;
+                    });
+                    plans.push({
+                        module, previous, next: { local: override.map(target => target.path).join(', ') }, local: override,
+                        entries, 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);
+                    // 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') {
+                        const entry = { destination: mapping.destination, assemblies: mapping.assemblies, path: path.posix.join(mapping.destination, assembly) };
+                        if (mapping.role === 'worker') {
+                            entry.role = 'worker';
+                            if (mapping.service)
+                                entry.service = mapping.service;
+                        }
+                        entries.push(entry);
+                    }
+                }
+                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] = manifestSource(plan.module, plan.local, moduleSources[plan.module]);
+                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, localTargets: plans.flatMap(plan => plan.local ?? []) };
+        }
+        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 server = document?.SystemConfig?.Services?.Server;
+        const raw = mapping.role === 'worker' ? server?.PluginWorkers?.['sys:string'] : 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