@guanjinke/artifact-client 1.11.0 → 1.12.0

package/dist/environment/types.d.ts

@@ -1,5 +1,5 @@
 import { ArtifactClient } from '../artifact-client';
-export type EnvironmentModule = 'dashboard' | 'reporting' | 'data-monitoring' | 'analysis' | 'sheets' | 'documents' | 'collaboration';
+export type EnvironmentModule = 'dashboard' | 'reporting' | 'data-monitoring' | 'analysis' | 'sheets' | 'documents' | 'collaboration' | 'patch';
 export interface EnvironmentOptions {
     root: string;
     major: string;
@@ -24,9 +24,10 @@ export interface LayoutMapping {
      * `resource` is a static tree deployed into the environment's web root for the
      * Server to serve (the built-in `dashboard-resource` module's 3D scene and map
      * assets). It carries no assembly, needs no `.runtimeconfig.json`, and adds
-     * nothing to `conf/Wyn.conf`.
+     * nothing to `conf/Wyn.conf`. `replace` overwrites one existing regular file
+     * instead of deploying a directory; the selectable `patch` module uses it.
      */
-    role: 'plugin' | 'worker' | 'server' | 'monitor' | 'service' | 'resource';
+    role: 'plugin' | 'worker' | 'server' | 'monitor' | 'service' | 'resource' | 'replace';
     service?: string;
     /**
      * Edition this mapping belongs to. A mapping without one is deployed for every
@@ -40,21 +41,22 @@ export interface LayoutMapping {
 interface EnvironmentArtifactBase {
     module: string;
     plugin: string;
-    version: string;
     /**
      * Remote object name of the artifact inside the version directory, or — for a
      * directory-of-files module — the remote directory holding its payload files.
-     * Never a credential-bearing URL.
+     * Never a credential-bearing URL. A resolved deferred replacement records no
+     * path: the provider's path would expose a name the module hides.
      */
-    path: string;
+    path?: string;
     mappings: LayoutMapping[];
 }
 /**
  * A module that publishes exactly one archive, downloaded and then extracted
  * before its mappings are laid out. This is the shape every module but
- * `builtin-samples` has.
+ * `builtin-samples` and `patch` has.
  */
 export interface EnvironmentArtifact extends EnvironmentArtifactBase {
+    version: string;
     /** File name of the single archive, relative to the version directory. */
     name: string;
     names?: undefined;
@@ -69,10 +71,36 @@ export interface EnvironmentArtifact extends EnvironmentArtifactBase {
  * artifact can never describe this module and vice versa.
  */
 export interface EnvironmentPayloadArtifact extends EnvironmentArtifactBase {
+    version: string;
     names: string[];
     name?: undefined;
 }
-export type PlannedArtifact = EnvironmentArtifact | EnvironmentPayloadArtifact;
+/**
+ * A selectable module whose version is only known while an environment is
+ * assembled.
+ *
+ * `patch` replaces one file inside the Server package, and the version of that
+ * replacement is the version of the component the Server package itself depends
+ * on. Neither value exists at plan time: the plan carries this descriptor after
+ * all core modules, and the builder resolves it from the Server tree it has just
+ * laid out. The descriptor deliberately carries no mapping: the mapping names
+ * the file the module replaces, and the module's real identity must stay out of
+ * every public document.
+ */
+export interface EnvironmentDeferredArtifact {
+    module: string;
+    /** The module's public label, never the publishing plugin. */
+    plugin: string;
+    deferred: true;
+    path?: undefined;
+    version?: undefined;
+    name?: undefined;
+    names?: undefined;
+    mappings?: undefined;
+}
+export type PlannedArtifact = EnvironmentArtifact | EnvironmentPayloadArtifact | EnvironmentDeferredArtifact;
+/** True for the plan descriptor whose version and payload resolve while assembling. */
+export declare function isDeferredArtifact(artifact: PlannedArtifact): artifact is EnvironmentDeferredArtifact;
 export type EnvironmentSchema = 'V91' | 'V100';
 export interface EnvironmentPlan {
     managed?: {

package/dist/environment/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/environment/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/environment/types.ts"],"names":[],"mappings":"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"}

package/dist/environment/types.js

@@ -1,3 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDeferredArtifact = isDeferredArtifact;
+/** True for the plan descriptor whose version and payload resolve while assembling. */
+function isDeferredArtifact(artifact) {
+    return artifact.deferred === true;
+}
 //# sourceMappingURL=types.js.map

package/dist/environment/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/environment/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/environment/types.ts"],"names":[],"mappings":";;AAwGA,gDAEC;AAHD,uFAAuF;AACvF,SAAgB,kBAAkB,CAAC,QAAyB;IAC1D,OAAQ,QAAmC,CAAC,QAAQ,KAAK,IAAI,CAAC;AAChE,CAAC"}

package/dist/environment/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/environment/update.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/environment/update.ts"],"names":[],"mappings":"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"}

package/dist/environment/update.js

@@ -40,6 +40,7 @@ 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 deferred_1 = require("./deferred");
 const archive_1 = require("./archive");
 const builder_1 = require("./builder");
 const config_1 = require("./config");
@@ -93,7 +94,49 @@ const requiredPackageFiles = {
  */
 const excludedCopyNames = (mapping) => mapping.role === 'server' ? [...serverOwnedFiles] : mapping.role === 'monitor' ? ['conf'] : [];
 /**
- * The modules a selection may name, from the same table `create-env` and the web
+ * Download the payload of a deferred module.
+ *
+ * It is published as files, not as an archive: the provider keeps the relative
+ * sub-path and the file is deployed exactly as downloaded, so nothing is
+ * extracted. Exactly one object is downloaded for `patch`. The public label is
+ * the only name in progress output or in errors.
+ */
+async function stageReplacement(client, module, version, payloads, workspace, onProgress) {
+    const entry = catalog_1.catalog[module];
+    const label = (0, catalog_1.moduleLabel)(entry);
+    const download = path.join(workspace, 'download', label);
+    try {
+        await fs.mkdir(download, { recursive: true });
+        onProgress?.(`[${label}] ${label}/${version}: Downloading replacement`);
+        const files = [];
+        for (const payload of payloads) {
+            await client.downloadArtifact(entry.plugin, version, payload.name, download);
+            const source = path.join(download, ...payload.name.split('/'));
+            await (0, builder_1.regularFile)(source);
+            files.push({ name: payload.name, source, sha256: await (0, builder_1.hashFile)(source) });
+        }
+        onProgress?.(`[${label}] ${label}/${version}: Download complete; replacement ready`);
+        return { version, files };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith(`Module ${label} could not be applied:`))
+            throw error;
+        throw new Error(`Module update failed for ${label}/${version} (download or layout).`);
+    }
+}
+/** One environment-relative Server path inside a staged Server package. */
+function stagedServerPath(staged, relative) {
+    const server = catalog_1.catalog.server.mappings.find(mapping => mapping.role === 'server');
+    const prefix = server ? `${server.destination}/` : '';
+    const inner = prefix && relative.startsWith(prefix) ? relative.slice(prefix.length) : relative;
+    return path.join(staged.expanded, ...(server?.source ? server.source.split('/') : []), ...inner.split('/'));
+}
+/** The version file inside a staged Server package, before it is laid out. */
+function stagedServerFile(staged, module) {
+    const descriptor = catalog_1.catalog[module].deferred;
+    return stagedServerPath(staged, descriptor.versionFile);
+}
+/** The modules a selection may name, from the same table `create-env` and the web
  * interface read.
  *
  * Reading it through the call keeps this module loadable on its own: the policy
@@ -185,6 +228,11 @@ function pushSpec(specs, seen, spec) {
     }
     else {
         validateUpdatableModule(spec.module);
+        // A deferred module's version is always the one recorded by the deployed (or
+        // newly staged) Server package. Pinning a different one would either be
+        // ignored or produce a mismatched environment, so it is refused.
+        if (catalog_1.catalog[spec.module].deferred && spec.version !== undefined)
+            throw new Error(`Module ${spec.module} takes its version from the deployed Server package: a pinned version is not supported.`);
         if (seen.has(allModules))
             throw new Error('Module spec all cannot be combined with individual modules.');
         const previous = seen.get(spec.module);
@@ -560,14 +608,17 @@ function environmentSchema(manifest, configuration) {
  * that policy. Returns the warning text, or undefined when the package is
  * complete.
  */
-async function verifyStagedPackage(module, staged, schema) {
+async function verifyStagedPackage(module, staged, schema, required = requiredPackageFiles[module] ?? []) {
     const label = `${staged.plugin}/${staged.version}/${staged.name}`;
-    for (const name of requiredPackageFiles[module] ?? []) {
+    for (const name of required) {
         try {
             await (0, builder_1.regularFile)(path.join(staged.expanded, name));
         }
+        // The Server's required file is the one the selectable patch replaces, so the
+        // message stays generic: its name must not be user-visible. Every other
+        // module's required file name is public and useful.
         catch {
-            throw new Error(`Module update failed for ${label}: the package is missing ${name}.`);
+            throw new Error(`Module update failed for ${label}: the package is missing ${module === 'server' ? 'a required runtime file' : name}.`);
         }
     }
     const relative = `xsd/${schema}/Wyn.conf.xsd`;
@@ -643,11 +694,17 @@ function mappingForAssembly(module, assembly) {
  * explicitly, for a build whose file name matches no assembly at all.
  */
 async function resolveLocalSource(entry, module, assembly, input) {
-    // Any built-in trailing module is never a developer-build target: it ships a
-    // static asset tree no local DLL could stand in for. Both are refused as
-    // explicit specs before this point (one internal, one create-only); this guard
-    // is the safety net for a trailing module a user could select, whose remote
-    // specs would keep working.
+    // A deferred module is a published replacement for one file the Server package
+    // owns; a developer build has no mapping the configuration could point at, so
+    // a local source is refused on its own terms before any path is looked at.
+    // The message names the module only.
+    if (catalog_1.catalog[module].deferred)
+        throw new Error(`Module ${module} is refreshed from its published artifact only and has no local source.`);
+    // Any built-in trailing module is never a developer-build target either: it
+    // ships a static asset tree no local DLL could stand in for. Both are refused
+    // as explicit specs before this point (one internal, one create-only); this
+    // guard is the safety net for a trailing module a user could select, whose
+    // remote specs would 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);
@@ -817,6 +874,21 @@ class EnvironmentUpdater {
                 onProgress?.(`${module} is refreshed with the Server package: its trees deploy inside the Server directory`);
             }
         }
+        // A Server refresh restores the unpatched file the Server package ships, so
+        // an installed deferred module is re-applied in the same call. Its version is
+        // resolved from the *new* package below, never from the old tree. Without a
+        // Server refresh it is only applied when the caller names it explicitly.
+        const autoReplaced = [];
+        if (remote.some(spec => spec.module === 'server')) {
+            for (const module of Object.keys(catalog_1.catalog)) {
+                if (!catalog_1.catalog[module].deferred || !installed.has(module) || parsed.some(spec => spec.module === module))
+                    continue;
+                parsed.push({ module });
+                remote.push({ module });
+                autoReplaced.push(module);
+                onProgress?.(`${module} is re-applied with the Server package: the new package replaces the file it patches`);
+            }
+        }
         // 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
@@ -847,15 +919,57 @@ class EnvironmentUpdater {
         try {
             const resolved = new Map();
             const staged = new Map();
+            const replacements = new Map();
             if (remote.length) {
                 const client = clientFactory();
-                for (const spec of remote) {
+                const direct = remote.filter(spec => !catalog_1.catalog[spec.module].deferred);
+                for (const spec of direct) {
                     onProgress?.(`Resolving ${catalog_1.catalog[spec.module].plugin}`);
                     resolved.set(spec.module, await resolveRemoteArtifact(client, entry, spec));
                 }
                 if (!dryRun)
-                    for (const spec of remote)
+                    for (const spec of direct)
                         staged.set(spec.module, await stageRemoteArtifact(client, resolved.get(spec.module), editionOf(entry), workspace, onProgress));
+                // A deferred module resolves after the direct artifacts are staged, so a
+                // Server refresh contributes the *new* package's version. Without a
+                // Server refresh the already deployed tree is the authority. A dry-run
+                // that refreshes the Server cannot know that version without downloading
+                // the package, so it reports the deferred resolution and stops there.
+                for (const spec of remote.filter(candidate => catalog_1.catalog[candidate.module].deferred)) {
+                    const module = spec.module;
+                    const source = catalog_1.catalog[module];
+                    const label = (0, catalog_1.moduleLabel)(source);
+                    const server = staged.get('server');
+                    let version;
+                    if (server) {
+                        version = await (0, deferred_1.deferredVersionAt)(source, stagedServerFile(server, module));
+                        // The replacement must overwrite an existing regular file in the new
+                        // package; checking the staged tree catches a package that no longer
+                        // ships it before anything has been written.
+                        for (const mapping of (0, deferred_1.replacementMappings)(source)) {
+                            const file = stagedServerPath(server, mapping.destination);
+                            const stat = await lstatOrUndefined(file);
+                            if (!stat)
+                                throw new Error(`Module ${label} could not be applied: the Server package holds no file to replace.`);
+                            if (!stat.isFile() || stat.isSymbolicLink())
+                                throw new Error(`Module ${label} could not be applied: the Server package holds no regular file to replace.`);
+                        }
+                    }
+                    else if (remote.some(candidate => candidate.module === 'server')) {
+                        onProgress?.(`${label}: version resolves from the refreshed Server package at execution time`);
+                        replacements.set(module, { version: '' });
+                        continue;
+                    }
+                    else
+                        version = await (0, deferred_1.deferredVersion)(source, entry.root);
+                    const payloads = await (0, deferred_1.deferredPayload)(source, version, client);
+                    if (dryRun) {
+                        onProgress?.(`${label}/${version}: resolved from the deployed Server package; nothing downloaded`);
+                        replacements.set(module, { version });
+                        continue;
+                    }
+                    replacements.set(module, await stageReplacement(client, module, version, payloads, 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
@@ -867,11 +981,16 @@ class EnvironmentUpdater {
             if (remote.some(spec => spec.module === 'server' || spec.module === 'monitoring') && !schema) {
                 throw new Error(`Module update for ${remote.filter(spec => spec.module === 'server' || spec.module === 'monitoring').map(spec => spec.module).join(' and ')} needs the configuration schema of ${entry.name}, which neither its manifest nor its conf/Wyn.conf records. Recreate the environment with create-env.`);
             }
+            // A planned deferred module validates the exact Server file it replaces,
+            // with a message that names only the module; the Server's own required-file
+            // check would otherwise report the same missing file by its internal name.
+            const deferredPlanned = remote.some(spec => catalog_1.catalog[spec.module].deferred);
             for (const spec of remote) {
                 const stagedArtifact = staged.get(spec.module);
                 if (!stagedArtifact || !schema || !(spec.module in requiredPackageFiles))
                     continue;
-                const warning = await verifyStagedPackage(spec.module, stagedArtifact, schema);
+                const required = spec.module === 'server' && deferredPlanned ? [] : requiredPackageFiles[spec.module];
+                const warning = await verifyStagedPackage(spec.module, stagedArtifact, schema, required);
                 if (warning)
                     warnings.push(warning);
             }
@@ -879,9 +998,11 @@ class EnvironmentUpdater {
             // A module may carry several local specs: plan it once, for all its targets.
             // 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)));
+            // directories, so a Server replacement must not wipe them again. A deferred
+            // module runs after `server` even when the caller wrote it first: the Server
+            // directory must hold the new package before it is patched.
+            const rank = (module) => plan_1.trailingModules.includes(module) ? 2 : catalog_1.catalog[module].deferred ? 1 : 0;
+            const planOrder = [...new Set(parsed.map(spec => spec.module))].sort((left, right) => rank(left) - rank(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 };
@@ -911,6 +1032,37 @@ class EnvironmentUpdater {
                     });
                     continue;
                 }
+                // A deferred module replaces one existing regular file and contributes
+                // no directory, plugin, worker, service or runtime requirement. Its
+                // version and payload were resolved above; nothing about the provider is
+                // recorded, and the target is checked before any write.
+                if (catalog_1.catalog[module].deferred) {
+                    const replacement = replacements.get(module);
+                    const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[module]);
+                    const version = replacement?.version || undefined;
+                    const files = [];
+                    if (replacement?.files?.length) {
+                        const mappings = (0, deferred_1.replacementMappings)(catalog_1.catalog[module]);
+                        for (const file of replacement.files) {
+                            const matches = mappings.filter(mapping => mapping.source === file.name);
+                            if (matches.length !== 1)
+                                throw new Error(`Module ${label} could not be applied: the replacement target is not configured.`);
+                            const destination = installationDirectory(entry.root, matches[0].destination);
+                            const stat = await lstatOrUndefined(destination);
+                            if (!stat)
+                                throw new Error(`Module ${label} could not be applied: the Server tree holds no file to replace.`);
+                            if (!stat.isFile() || stat.isSymbolicLink())
+                                throw new Error(`Module ${label} could not be applied: the Server tree holds no regular file to replace.`);
+                            files.push({ source: file.source, destination, sha256: file.sha256 });
+                        }
+                    }
+                    plans.push({
+                        module, previous, next: version ? { version } : {},
+                        ...(files.length ? { replacement: { version: version, files } } : {}),
+                        entries: [], copies: [], removals: [], preserved: [], copiedDirectories: [], removedDirectories: [],
+                    });
+                    continue;
+                }
                 const remoteArtifact = resolved.get(module);
                 const stagedArtifact = staged.get(module);
                 const copies = [];
@@ -1029,6 +1181,28 @@ class EnvironmentUpdater {
                     }
                     delete moduleSources[plan.module];
                 }
+                if (plan.replacement) {
+                    // The record keeps the public label, the resolved version and the
+                    // payload's SHA256. No remote path and no mapping are written: both
+                    // would expose a name the module hides.
+                    const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[plan.module]);
+                    const replacement = { module: plan.module, plugin: label, version: plan.replacement.version, name: label };
+                    const index = nextArtifacts.findIndex(candidate => candidate.module === plan.module);
+                    if (index < 0)
+                        nextArtifacts.push(replacement);
+                    else
+                        nextArtifacts[index] = { ...nextArtifacts[index], ...replacement };
+                    for (const file of plan.replacement.files) {
+                        const download = { plugin: label, version: plan.replacement.version, name: label, sha256: file.sha256 };
+                        const downloadIndex = nextDownloads.findIndex(candidate => candidate.plugin === label);
+                        if (downloadIndex < 0)
+                            nextDownloads.push(download);
+                        else
+                            nextDownloads[downloadIndex] = download;
+                    }
+                    requirements = requirements.filter(line => !line.endsWith(` (${plan.module})`));
+                    delete moduleSources[plan.module];
+                }
                 if (plan.local)
                     moduleSources[plan.module] = manifestSource(plan.module, plan.local, moduleSources[plan.module]);
                 // First installing a module records it the way `create-env` would: a
@@ -1108,6 +1282,8 @@ class EnvironmentUpdater {
             }
             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 (autoReplaced.length)
+                warnings.push(`${autoReplaced.join(', ')} was re-applied with the Server package: the new package ships the file it replaces, so it was applied again.`);
             if (removedCreateOnly.length)
                 warnings.push(`${removedCreateOnly.join(', ')} was removed with the Server package: it is deployed only when an environment is created.`);
             if (!dryRun) {
@@ -1132,6 +1308,25 @@ class EnvironmentUpdater {
                         await (0, builder_1.copyTree)(copy.source, copy.destination, copy.exclude);
                     for (const file of plan.preserved)
                         await fs.copyFile(file.source, path.join(file.directory, file.name));
+                    // The replacement is applied after the directory it lives in has been
+                    // copied, so a Server refresh cannot overwrite it again. The target is
+                    // re-checked here and every error names the module only.
+                    if (plan.replacement) {
+                        const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[plan.module]);
+                        try {
+                            for (const file of plan.replacement.files) {
+                                const stat = await fs.lstat(file.destination).catch(() => undefined);
+                                if (!stat)
+                                    throw new Error('missing');
+                                if (!stat.isFile() || stat.isSymbolicLink())
+                                    throw new Error('not a regular file');
+                                await fs.copyFile(file.source, file.destination);
+                            }
+                        }
+                        catch {
+                            throw new Error(`Module ${label} could not be applied: the Server tree holds no regular file to replace.`);
+                        }
+                    }
                     if (plan.configurationAssets) {
                         onProgress?.(`Refreshing Monitor configuration assets in ${path.relative(entry.root, plan.configurationAssets.destination)}`);
                         await mergeConfigurationAssets(plan.configurationAssets.source, plan.configurationAssets.destination);