@guanjinke/artifact-client 1.8.0 → 1.10.0

package/dist/environment/update.js

@@ -48,7 +48,6 @@ const registry_1 = require("./registry");
 const validate_1 = require("./validate");
 const process_1 = require("./process");
 const posix_process_1 = require("./posix-process");
-const package_resource_1 = require("./package-resource");
 const atomic_1 = require("../utils/atomic");
 const local_path_1 = require("../utils/local-path");
 /** Same parser options as the creation path, so a rewrite round-trips identically. */
@@ -57,8 +56,13 @@ const builderOptions = { ignoreAttributes: false, format: true, suppressEmptyNod
 const windowsPath = (value, platform) => (0, local_path_1.nativeSeparators)(value, platform);
 /** The separator the recorded entries use on the target platform. */
 const separatorOf = (platform) => (platform === 'win32' ? '\\' : '/');
-/** Every catalog module can be updated remotely; local overrides are excluded per environment. */
-exports.updatableModules = Object.keys(catalog_1.catalog).sort();
+/**
+ * Every catalog module an update may refresh. The create-only modules are
+ * excluded: they seed data the product imports once, when the Server starts for
+ * the first time, so an update never refreshes, preserves or re-deploys them —
+ * and the web update picker reads this same list.
+ */
+exports.updatableModules = Object.keys(catalog_1.catalog).filter(module => !catalog_1.catalog[module].createOnly).sort();
 /**
  * Server-root settings the environment owns.
  *
@@ -95,10 +99,21 @@ const excludedCopyNames = (mapping) => mapping.role === 'server' ? [...serverOwn
  */
 const selectableModules = () => new Set([...new Set(Object.values(plan_1.optionalModulesByEdition).flat())]);
 const installationDirectory = (root, destination) => path.join(root, ...destination.split('/'));
+/**
+ * The edition an environment deploys. The registry records a free string and
+ * only `en` is special everywhere else in this module, so anything else counts
+ * as `cn`, exactly like the edition gate below does.
+ */
+const editionOf = (entry) => entry.edition === 'en' ? 'en' : 'cn';
 function validateUpdatableModule(module) {
-    if (Object.prototype.hasOwnProperty.call(catalog_1.catalog, module))
-        return;
-    throw new Error(`Unsupported module "${module}": supported modules are ${Object.keys(catalog_1.catalog).sort().join(', ')}.`);
+    // `hasOwnProperty` keeps prototype names (`constructor`) out of the catalog.
+    if (!Object.prototype.hasOwnProperty.call(catalog_1.catalog, module))
+        throw new Error(`Unsupported module "${module}": supported modules are ${exports.updatableModules.join(', ')}.`);
+    // A create-only module is refused before anything else happens — before the
+    // registry, the manifest or the configuration is read — because no update can
+    // produce it: it is deployed only while the environment is created.
+    if (catalog_1.catalog[module].createOnly)
+        throw new Error(`Module ${module} is create-only: it is deployed only when the environment is created and is never refreshed, preserved or re-deployed by update-env. Recreate the environment with create-env to get it again.`);
 }
 /** `all` is the only allowed pseudo-module: every configured module from remote. */
 const allModules = 'all';
@@ -382,10 +397,9 @@ async function readManifest(root) {
     }
     if (manifest.selectedModules !== undefined && (!Array.isArray(manifest.selectedModules) || manifest.selectedModules.some(module => typeof module !== 'string')))
         throw new Error('Environment manifest is unreadable.');
-    // Only the entry name is required: the resource list is written by this package
-    // for the package's own trees, and unknown extra fields are preserved as-is.
-    if (manifest.resources !== undefined && (!Array.isArray(manifest.resources) || manifest.resources.some(resource => !resource || typeof resource !== 'object' || Array.isArray(resource) || typeof resource.name !== 'string')))
-        throw new Error('Environment manifest is unreadable.');
+    // A stale `resources` key written by an older version is ignored here and
+    // dropped when the manifest is rewritten: the key belongs to the removed
+    // packaged-resource feature, not to the environment's configuration.
     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 ?? {})) {
@@ -444,7 +458,7 @@ async function resolveRemoteArtifact(client, entry, spec) {
     catch {
         throw new Error(`Unable to resolve artifacts for ${source.plugin}/${spec.version ?? entry.major}.`);
     }
-    const name = source.filename(version, entry.edition);
+    const name = (0, catalog_1.archiveName)(source, 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}.`);
@@ -454,7 +468,7 @@ async function resolveRemoteArtifact(client, entry, spec) {
     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) {
+async function stageRemoteArtifact(client, artifact, edition, 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}`);
@@ -469,10 +483,16 @@ async function stageRemoteArtifact(client, artifact, workspace, onProgress) {
         onProgress?.(`${label}: Extracting and validating ZIP`);
         await (0, archive_1.extractArchive)(archive, expanded);
         const assemblies = new Map();
-        for (const mapping of artifact.mappings) {
+        // A mapping of the other edition is never required: its source directory
+        // does not even have to be in the archive.
+        for (const mapping of (0, catalog_1.editionMappings)(artifact.mappings, edition)) {
             const source = path.join(expanded, mapping.source);
             if (!(await fs.lstat(source)).isDirectory())
                 throw new Error('Required source directory missing.');
+            // A `resource` mapping is a static tree with no assembly to verify and no
+            // runtimeconfig to read; the Server only serves it.
+            if (mapping.role === 'resource')
+                continue;
             if (mapping.role === 'service' && mapping.assemblies.length === 0)
                 continue;
             const present = [];
@@ -616,6 +636,12 @@ function mappingForAssembly(module, assembly) {
  * explicitly, for a build whose file name matches no assembly at all.
  */
 async function resolveLocalSource(entry, module, assembly, input) {
+    // The built-in resource module is never a developer-build target: it ships a
+    // static asset tree that no local DLL could stand in for, so a local source is
+    // refused on its own terms before any path is even looked at. Remote specs
+    // (latest, pinned and `all`) keep working.
+    if (plan_1.trailingModules.includes(module))
+        throw new Error(`Module ${module} is built in and has no local source: it ships the 3D scene and map assets and is always deployed from its published artifact. Refresh it from the cloud (\`${module}\`, \`${module}:<version>\` or \`all\`).`);
     const mappings = localMappings(module);
     // The Server, Monitor and collaboration deployments are whole services, not a
     // plugin the Server loads: a developer build has no place to point the
@@ -705,14 +731,12 @@ class EnvironmentUpdater {
     registry;
     processes;
     platform;
-    bundledResources;
     onProgress;
     constructor(dependencies = {}) {
         this.dependencies = dependencies;
         this.registry = dependencies.registry ?? new registry_1.EnvironmentRegistry();
         this.processes = dependencies.processes ?? (process.platform === 'win32' ? new process_1.WindowsProcessBackend() : new posix_process_1.PosixProcessBackend());
         this.platform = dependencies.platform ?? process.platform;
-        this.bundledResources = dependencies.bundledResourcesDirectory ?? (0, package_resource_1.bundledResourcesDirectory)();
         this.onProgress = dependencies.onProgress;
     }
     async update(name, specs, clientFactory, options = {}) {
@@ -720,9 +744,8 @@ class EnvironmentUpdater {
         const onProgress = options.onProgress ?? this.onProgress;
         onProgress?.('Validating module specs');
         let parsed = normalizeModuleSpecs(specs);
-        // No module spec is a valid request: it (re)lays out the bundled resources
-        // alone, which is how an environment created before they were bundled gets
-        // them without touching a single module.
+        if (!parsed.length)
+            throw new Error('At least one module spec is required: pass `all` or one or more module names (module, module:<version> or module=<local path>).');
         const entry = await this.registry.get(name);
         onProgress?.(`Validating environment ${entry.name} at ${entry.root}`);
         await (0, validate_1.validateEnvironmentRoot)(entry, this.registry.directory);
@@ -766,6 +789,23 @@ class EnvironmentUpdater {
             localOverrides.set(spec.module, targets);
         }
         const remote = parsed.filter(spec => spec.localPath === undefined);
+        // The built-in resource module deploys its trees *inside* the Server
+        // directory, and a Server refresh replaces that whole directory. An
+        // environment that has it therefore re-deploys it from its own artifact
+        // whenever the Server is refreshed in the same call: a remote-only module has
+        // no local copy to restore the trees from. A create-only trailing module is
+        // never re-deployed: the Server refresh simply drops what it had seeded.
+        const autoRefreshed = [];
+        if (remote.some(spec => spec.module === 'server')) {
+            for (const module of plan_1.trailingModules) {
+                if (catalog_1.catalog[module].createOnly || !installed.has(module) || parsed.some(spec => spec.module === module))
+                    continue;
+                parsed.push({ module });
+                remote.push({ module });
+                autoRefreshed.push(module);
+                onProgress?.(`${module} is refreshed with the Server package: its trees deploy inside the Server directory`);
+            }
+        }
         // Smart documents cannot run without the collaboration service, which
         // create-env deploys and declares in the Server configuration alongside
         // documents. Installing documents into an environment with no collaboration
@@ -779,26 +819,6 @@ class EnvironmentUpdater {
             throw new Error(`Cannot update modules from a remote source while ${entry.name} is ${state}: deployed files may be in use. Run \`afm env stop ${entry.name}\` first.`);
         if (!remote.length && state !== 'ready' && state !== 'stopped' && state !== 'running')
             throw new Error(`Cannot update modules while ${entry.name} is ${state}: the runtime identity must be verified before its files are changed. Run \`afm env stop ${entry.name}\` first.`);
-        // The packaged 3D scene assets belong to every environment, not only to one
-        // that create-env assembled: the plan below finds the files an environment is
-        // still missing (or that differ) and the apply writes them with the rest of
-        // the update. Planning touches nothing and runs before any download or write,
-        // so an incomplete installation fails loudly with the path it expected and
-        // leaves the environment exactly as it was.
-        //
-        // The assets live at `Server/wwwroot/3DScene`, so refreshing the server
-        // module removes the whole tree they are in. Plan every packaged file as
-        // missing in that case: comparing against the content that is about to be
-        // deleted would report every file identical and lay nothing out at all.
-        const refreshesServer = remote.some(spec => spec.module === 'server');
-        const resourceSource = (0, package_resource_1.bundledResourceDirectory)(package_resource_1.sceneResourceName, this.bundledResources);
-        const resourceDestination = path.join(entry.root, ...package_resource_1.sceneResourceDestination.split('/'));
-        onProgress?.(`Checking bundled 3D scene resources in ${package_resource_1.sceneResourceDestination}`);
-        const resourcePlan = await (0, package_resource_1.planBundledResource)(resourceSource, resourceDestination, refreshesServer);
-        const resourceWrites = resourcePlan.added + resourcePlan.updated;
-        const resource = { name: package_resource_1.sceneResourceName, source: resourceSource, destination: package_resource_1.sceneResourceDestination, files: resourcePlan.files.length, added: resourcePlan.added, updated: resourcePlan.updated };
-        const resourceSummary = `${resourcePlan.files.length - resourceWrites} identical, ${resourcePlan.added} missing, ${resourcePlan.updated} different`;
-        onProgress?.(`Bundled 3D scene resources in ${package_resource_1.sceneResourceDestination}: ${dryRun ? 'dry run; ' : ''}${resourceSummary}`);
         const downloads = [...(manifest.downloads ?? [])];
         const selectedModules = stringListOrUndefined(manifest.selectedModules);
         const autoAddedModules = stringListOrUndefined(manifest.autoAddedModules);
@@ -811,7 +831,7 @@ class EnvironmentUpdater {
         // runtimeconfig files, so an update replaces the entries of the modules it
         // refreshes and leaves every other module's alone.
         let requirements = Array.isArray(manifest.requirements) ? manifest.requirements.filter((line) => typeof line === 'string') : [];
-        const workspace = !dryRun && (remote.length > 0 || resourceWrites > 0) ? await fs.mkdtemp(path.join(path.dirname(entry.root), '.afm-env-')) : undefined;
+        const workspace = !dryRun && remote.length > 0 ? await fs.mkdtemp(path.join(path.dirname(entry.root), '.afm-env-')) : undefined;
         const warnings = [];
         try {
             const resolved = new Map();
@@ -824,7 +844,7 @@ class EnvironmentUpdater {
                 }
                 if (!dryRun)
                     for (const spec of remote)
-                        staged.set(spec.module, await stageRemoteArtifact(client, resolved.get(spec.module), workspace, onProgress));
+                        staged.set(spec.module, await stageRemoteArtifact(client, resolved.get(spec.module), editionOf(entry), workspace, onProgress));
             }
             const configured = await fs.readFile(path.join(entry.root, 'conf', 'Wyn.conf'), 'utf8');
             // A Server or Monitor package is only usable when it still serves the
@@ -846,7 +866,12 @@ class EnvironmentUpdater {
             }
             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))]) {
+            // The built-in trailing modules are planned last, in the same order
+            // `create-env` assembles: their trees live inside other modules'
+            // directories, so a Server replacement must not wipe them again.
+            const planOrder = [...new Set(parsed.map(spec => spec.module))]
+                .sort((left, right) => Number(plan_1.trailingModules.includes(left)) - Number(plan_1.trailingModules.includes(right)));
+            for (const module of planOrder) {
                 const artifact = artifacts.find(candidate => candidate.module === module);
                 const previous = moduleSources[module] ? { local: moduleSources[module].path } : { version: artifact?.version };
                 const override = localOverrides.get(module);
@@ -885,8 +910,12 @@ class EnvironmentUpdater {
                 const entries = [];
                 let configurationAssets;
                 let configurationLink;
-                for (const mapping of remoteArtifact.mappings) {
+                // Only the mappings this environment's edition deploys: the other
+                // edition's directory is never removed, copied or referenced.
+                for (const mapping of (0, catalog_1.editionMappings)(remoteArtifact.mappings, editionOf(entry))) {
                     const destination = installationDirectory(entry.root, mapping.destination);
+                    // A `resource` directory the module already deployed is replaced, never
+                    // merged, and it contributes no plugin, worker, service or runtime entry.
                     if (await exists(destination)) {
                         removals.push(destination);
                         removedDirectories.push(mapping.destination);
@@ -903,6 +932,8 @@ class EnvironmentUpdater {
                     if (stagedArtifact)
                         copies.push({ source: path.join(stagedArtifact.expanded, mapping.source), destination, exclude: excludedCopyNames(mapping) });
                     copiedDirectories.push(mapping.destination);
+                    if (mapping.role === 'resource')
+                        continue;
                     // A native out-of-process service has no assembly and is declared as an
                     // empty node: the Server loads it from that entry and supplies the rest.
                     if (mapping.role === 'service') {
@@ -975,9 +1006,10 @@ class EnvironmentUpdater {
                             nextDownloads[downloadIndex] = download;
                         // The requirements the old artifact needed are gone with it: re-read
                         // the ones the new package actually declares, per deployed mapping.
+                        // A resource mapping is a static tree: it declares none.
                         requirements = requirements.filter(line => !line.endsWith(` (${plan.module})`));
-                        for (const mapping of plan.artifact.mappings) {
-                            if (mapping.role === 'service')
+                        for (const mapping of (0, catalog_1.editionMappings)(plan.artifact.mappings, editionOf(entry))) {
+                            if (mapping.role === 'service' || mapping.role === 'resource')
                                 continue;
                             for (const framework of await (0, builder_1.runtimeRequirements)(path.join(plan.staged.expanded, mapping.source))) {
                                 requirements.push(`${framework.name} ${framework.version} (${plan.module})`);
@@ -1010,6 +1042,32 @@ class EnvironmentUpdater {
                 autoAddedModules.length = 0;
                 autoAddedModules.push(...unique);
             }
+            // A create-only module deploys its payload inside the Server directory and is
+            // never refreshed, so a Server refresh replaces the tree it owns: the module
+            // is gone from the environment, and its record goes with it — the manifest
+            // and the registry would otherwise keep claiming a deployment that is not
+            // there any more.
+            const removedCreateOnly = [];
+            if (plans.some(plan => plan.module === 'server')) {
+                for (const module of Object.keys(catalog_1.catalog)) {
+                    if (catalog_1.catalog[module].createOnly !== true || !installed.has(module) || plans.some(plan => plan.module === module))
+                        continue;
+                    const plugin = catalog_1.catalog[module].plugin;
+                    for (let index = nextArtifacts.length - 1; index >= 0; index -= 1)
+                        if (nextArtifacts[index].module === module)
+                            nextArtifacts.splice(index, 1);
+                    for (let index = nextDownloads.length - 1; index >= 0; index -= 1)
+                        if (nextDownloads[index].plugin === plugin)
+                            nextDownloads.splice(index, 1);
+                    for (let index = requirements.length - 1; index >= 0; index -= 1)
+                        if (requirements[index].endsWith(` (${module})`))
+                            requirements.splice(index, 1);
+                    if (autoAddedModules)
+                        autoAddedModules.splice(0, autoAddedModules.length, ...autoAddedModules.filter(name => name !== module));
+                    delete moduleSources[module];
+                    removedCreateOnly.push(module);
+                }
+            }
             const nextManifest = { ...manifest, artifacts: nextArtifacts, downloads: nextDownloads, requirements: [...new Set(requirements)] };
             if (autoAddedModules)
                 nextManifest.autoAddedModules = autoAddedModules;
@@ -1019,19 +1077,10 @@ class EnvironmentUpdater {
                 delete nextManifest.moduleSources;
             if (selectedModules)
                 nextManifest.selectedModules = selectedModules;
-            // The resource is recorded in place, in exactly the shape create-env writes:
-            // a second update finds the entry and refreshes it instead of adding a
-            // duplicate. The result carries the added/updated counts; the manifest keeps
-            // the durable four-field description.
-            const resources = [...(manifest.resources ?? [])];
-            const recorded = resources.findIndex(candidate => candidate.name === package_resource_1.sceneResourceName);
-            const record = { name: package_resource_1.sceneResourceName, source: resource.source, destination: resource.destination, files: resource.files };
-            if (recorded < 0)
-                resources.push(record);
-            else
-                resources[recorded] = { ...resources[recorded], ...record };
-            nextManifest.resources = resources;
-            const modules = [...new Set([...entry.modules, ...plans.filter(plan => !installed.has(plan.module) && selectable.has(plan.module)).map(plan => plan.module)])].sort();
+            // A stale `resources` key from an older manifest is dropped here: the
+            // packaged-resource feature is gone and nothing records it any more.
+            delete nextManifest.resources;
+            const modules = [...new Set([...entry.modules, ...plans.filter(plan => !installed.has(plan.module) && selectable.has(plan.module)).map(plan => plan.module)])].filter(module => !removedCreateOnly.includes(module)).sort();
             const localModules = Object.keys(moduleSources).sort();
             if (state === 'running')
                 warnings.push(`${entry.name} is running; restart it to load the updated modules.`);
@@ -1046,6 +1095,10 @@ class EnvironmentUpdater {
             if (parsed.some(spec => spec.module === 'documents') && !parsed.some(spec => spec.module === 'collaboration')) {
                 warnings.push('documents was refreshed without collaboration; the smart documents plugin may expect the deployed collaboration service version, so refresh collaboration too.');
             }
+            if (autoRefreshed.length)
+                warnings.push(`${autoRefreshed.join(', ')} was refreshed with the Server package: its trees live inside the Server directory and would otherwise be lost.`);
+            if (removedCreateOnly.length)
+                warnings.push(`${removedCreateOnly.join(', ')} was removed with the Server package: it is deployed only when an environment is created.`);
             if (!dryRun) {
                 for (const plan of plans) {
                     // Take the environment-owned settings aside first, and drop the Monitor
@@ -1075,20 +1128,13 @@ class EnvironmentUpdater {
                     if (plan.configurationLink)
                         await fs.symlink(path.join(entry.root, 'conf'), plan.configurationLink, 'junction');
                 }
-                // The staged resources are written with the module changes, before the
-                // manifest that records them; a failure rolls the layout back.
-                if (resourceWrites) {
-                    if (!workspace)
-                        throw new Error('Missing staging workspace for the bundled resource layout.');
-                    onProgress?.(`Laying out bundled 3D scene resources into ${package_resource_1.sceneResourceDestination}`);
-                    const applied = await (0, package_resource_1.applyBundledResource)(resourceSource, resourceDestination, resourcePlan, path.join(workspace, 'replaced-resources'));
-                    if (applied.added.length !== resourcePlan.added || applied.updated.length !== resourcePlan.updated)
-                        throw new Error('Bundled resource layout did not match its plan.');
-                }
-                // A resource-only update (no module spec) leaves the Server configuration
-                // exactly as it is: the assets need no plugin, worker or service entry.
-                onProgress?.(plans.length ? 'Writing configuration, manifest and registry record' : 'Writing manifest and registry record');
-                if (plans.length)
+                // Only a plan that really contributes something to the configuration
+                // rewrites it: the built-in dashboard-resource module adds no plugin,
+                // worker or service entry, so refreshing it alone leaves `conf/Wyn.conf`
+                // exactly as it is instead of round-tripping it through the XML builder.
+                const configurationChanged = plans.some(plan => plan.entries.length > 0 || plan.configurationAssets !== undefined || plan.configurationLink !== undefined);
+                onProgress?.(configurationChanged ? 'Writing configuration, manifest and registry record' : 'Writing manifest and registry record');
+                if (configurationChanged)
                     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 => {
@@ -1104,10 +1150,10 @@ class EnvironmentUpdater {
                         delete entries[index].localModules;
                 });
             }
-            const restartRequired = !dryRun && (changes.length > 0 || resourceWrites > 0);
+            const restartRequired = !dryRun && changes.length > 0;
             if (restartRequired)
-                onProgress?.(`${entry.name}: ${changes.length ? 'modules updated' : 'bundled resources laid out'}; restart the environment to load the change (no service was started).`);
-            return { name: entry.name, root: entry.root, dryRun, changes, skipped, restartRequired, warnings, localTargets: plans.flatMap(plan => plan.local ?? []), resource };
+                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)