@guanjinke/artifact-client 1.4.0 → 1.5.0

package/dist/environment/update.js

@@ -67,19 +67,26 @@ 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();
+        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 };
+        return { module, localPath, ...(assembly !== undefined ? { assembly } : {}) };
     }
     const colon = value.indexOf(':');
     if (colon >= 0) {
@@ -100,8 +107,16 @@ function parseModuleSpec(value) {
         return { module: allModules };
     return { module };
 }
-/** Record one parsed spec, enforcing "all alone" and duplicate rules. */
+/**
+ * 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.');
@@ -112,10 +127,11 @@ function pushSpec(specs, seen, spec) {
         validateUpdatableModule(spec.module);
         if (seen.has(allModules))
             throw new Error('Module spec all cannot be combined with individual modules.');
-        if (seen.has(spec.module))
+        const previous = seen.get(spec.module);
+        if (previous !== undefined && (previous === 'remote' || kind === 'remote'))
             throw new Error(`Duplicate module in one update: ${spec.module}.`);
     }
-    seen.add(spec.module);
+    seen.set(spec.module, kind);
     specs.push(spec);
 }
 /**
@@ -130,7 +146,7 @@ function parseModuleSpecs(values) {
     if (!Array.isArray(values))
         throw new Error('Module specs must be an array of strings.');
     const specs = [];
-    const seen = new Set();
+    const seen = new Map();
     for (const value of values) {
         const text = String(value ?? '');
         for (const fragment of text.includes('=') ? text.split(',') : text.split(/[\s,]+/)) {
@@ -146,7 +162,7 @@ function normalizeModuleSpecs(values) {
     if (!Array.isArray(values))
         throw new Error('Module specs must be an array.');
     const specs = [];
-    const seen = new Set();
+    const seen = new Map();
     const push = (spec) => pushSpec(specs, seen, spec);
     for (const value of values) {
         if (typeof value === 'string') {
@@ -159,10 +175,11 @@ function normalizeModuleSpecs(values) {
         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)
+            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;
@@ -171,37 +188,28 @@ function normalizeModuleSpecs(values) {
             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 } : {}) });
+        push({ module, ...(version !== undefined ? { version } : {}), ...(localPath !== undefined ? { localPath } : {}), ...(assembly !== undefined ? { assembly } : {}) });
     }
     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'];
+/** 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.');
-    const strings = list.map(value => value.trim());
+    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) {
@@ -220,16 +228,64 @@ function patchEnvironmentConfiguration(xml, entries) {
             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;
+    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.');
@@ -270,8 +326,37 @@ async function readManifest(root) {
         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`;
@@ -348,45 +433,98 @@ 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}`);
     }
 }
-/** 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; });
+/** 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: ${target}.`);
-    let dll;
+        throw new Error(`Local source not found: ${source}.`);
     if (stat.isSymbolicLink())
-        throw new Error(`Local source must be a regular file or directory: ${target}.`);
+        throw new Error(`Local source must be a regular file or directory: ${source}.`);
+    const selected = [];
+    const inactive = [];
     if (stat.isFile()) {
-        if (path.extname(target).toLowerCase() !== '.dll')
-            throw new Error(`Local source must be a .dll file: ${target}.`);
-        dll = target;
+        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 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);
+        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>.`);
         }
-        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] };
+        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.
@@ -442,12 +580,23 @@ class EnvironmentUpdater {
             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;
-            localOverrides.set(spec.module, await resolveLocalSource(entry, spec.module, catalog_1.catalog[spec.module].mappings, spec.localPath));
+            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);
@@ -476,26 +625,33 @@ class EnvironmentUpdater {
             }
             const configured = await fs.readFile(path.join(entry.root, 'conf', 'Wyn.conf'), 'utf8');
             const plans = [];
-            for (const spec of parsed) {
-                const module = spec.module;
+            // 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 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);
+                    for (const target of override) {
+                        const destination = installationDirectory(entry.root, target.destination);
                         if (!await exists(destination))
                             continue;
                         removals.push(destination);
-                        removedDirectories.push(mapping.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.dll }, local: override,
-                        entries: pluginMappings.map(mapping => ({ destination: mapping.destination, assemblies: mapping.assemblies, path: override.dll })),
-                        copies: [], removals, copiedDirectories: [], removedDirectories,
+                        module, previous, next: { local: override.map(target => target.path).join(', ') }, local: override,
+                        entries, copies: [], removals, copiedDirectories: [], removedDirectories,
                     });
                     continue;
                 }
@@ -516,8 +672,17 @@ class EnvironmentUpdater {
                         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) });
+                    // 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');
@@ -562,7 +727,7 @@ class EnvironmentUpdater {
                     delete moduleSources[plan.module];
                 }
                 if (plan.local)
-                    moduleSources[plan.module] = { type: 'local', path: plan.local.dll, pluginDirectories: plan.local.pluginDirectories };
+                    moduleSources[plan.module] = manifestSource(plan.module, plan.local, moduleSources[plan.module]);
                 if (!installed.has(plan.module) && plan.module !== 'common' && selectedModules)
                     selectedModules.push(plan.module);
             }
@@ -610,7 +775,7 @@ class EnvironmentUpdater {
             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 };
+            return { name: entry.name, root: entry.root, dryRun, changes, skipped, restartRequired, warnings, localTargets: plans.flatMap(plan => plan.local ?? []) };
         }
         finally {
             if (workspace)
@@ -623,7 +788,8 @@ exports.EnvironmentUpdater = EnvironmentUpdater;
 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 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) {