@detergent-software/atk 8.4.2 → 8.4.3-dev.2

package/build/lib/updater.js

@@ -1,13 +1,14 @@
 import { join } from 'node:path';
 import { compare, valid } from 'semver';
 import { getPlacement, resolveInstalledPaths } from './adapter.js';
-import { isExcludedForTool, supportsType } from './asset-tools.js';
+import { declarationAllows, isExcludedForTool, supportsType } from './asset-tools.js';
 import { getCredential } from './auth.js';
 import { getConfigEntriesForTool } from './config-entries.js';
 import { ApiCodeError, asSentence, errorGuidance, errorMessage, isRunWideFailure, } from './errors.js';
 import { restoreFiles, snapshotFiles } from './file-snapshot.js';
-import { executeInstallPlan, fetchPlanFiles, FileConflictError, installFailureMessage, InstallPlanError, } from './installer.js';
+import { executeInstallPlan, fetchPlanFiles, FileConflictError, InstallerError, installFailureMessage, InstallPlanError, } from './installer.js';
 import { addAssetToLockfile, findDependencyAsset, findDependents, findInstalledAsset, getLockfilePath, readLockfile, writeLockfile, } from './lockfile.js';
+import { withoutKeptDependencies } from './multi-tool-install.js';
 import { formatOrgName, parseOrgFromName, scopeSwitchGuidance } from './org.js';
 import { findAsset } from './registry.js';
 import { resolveInstallPlan } from './resolver.js';
@@ -64,6 +65,18 @@ export function checkPinMismatches(lockfile) {
         ]
         : []);
 }
+/**
+ * Whether the manifest of `version` of the asset lets the adapter's tool take it (see
+ * {@link declarationAllows}); only a hook's declaration decides that. A version the registry lacks
+ * in the asset's scope counts as allowed, so the update itself reports it.
+ */
+export function declarationAllowsVersion(registry, asset, version, adapter) {
+    if (asset.type !== 'hook')
+        return true;
+    const found = findAsset(registry, asset.name, asset.type, version, asset.org);
+    const tools = found?.asset.org === asset.org ? found?.versionData.tools : undefined;
+    return declarationAllows(asset.type, tools, adapter.tool);
+}
 /**
  * The installed asset `atk update <spec>` names. `@org/name` names that org's entry only. A
  * bare name resolves the way `install` resolved it: the lockfile org's entry, else the global
@@ -98,186 +111,7 @@ export function findUpdateTarget(lockfile, spec, { type, version } = {}) {
  * download, so the rollback needs no second download.
  */
 export async function updateAsset(assetName, installed, registry, options) {
-    const { adapter, onProgress, projectDir, targetVersion } = options;
-    // Resolve the target version — defaults to latest when targetVersion is undefined
-    const resolved = findAsset(registry, assetName, installed.type, targetVersion, installed.org);
-    if (!resolved) {
-        if (targetVersion) {
-            throw new UpdaterError(`Asset "${assetName}" version "${targetVersion}" not found in registry.`);
-        }
-        throw new UpdaterError(`Asset "${assetName}" not found in registry.`);
-    }
-    if (resolved.asset.org !== installed.org) {
-        throw scopeSwitchError(installed, resolved.asset);
-    }
-    const toVersion = resolved.version;
-    if (!isNewer(toVersion, installed.version)) {
-        if (targetVersion) {
-            throw new UpdaterError(`Asset "${assetName}" is already at or ahead of the requested version (installed: v${installed.version}, requested: v${toVersion}).`);
-        }
-        throw new UpdaterError(`Asset "${assetName}" is already at the latest version (v${installed.version}).`);
-    }
-    const fromVersion = installed.version;
-    // Capture old dependencies before uninstalling
-    const oldDeps = installed.dependencies ?? [];
-    // Download the target version before removing anything, so a refused download (an outdated
-    // CLI, an expired sign-in, the API down) leaves the installed version in place.
-    const plan = planFor(registry, installed, toVersion);
-    onProgress?.(`Downloading ${assetName}@${toVersion}...`);
-    let files;
-    try {
-        files = await fetchPlanFiles(plan, adapter);
-    }
-    catch (downloadError) {
-        throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${failureReason(downloadError, installed)} ` +
-            `v${fromVersion} is still installed.`, errorGuidance(downloadError));
-    }
-    // Capture what the update can change, so a failed uninstall or install restores it without the network.
-    let snapshot;
-    // The version the lockfile records now. In a multi-tool update an earlier tool may already
-    // have moved it past `fromVersion`, which a restore then puts back.
-    let lockedVersion;
-    // The asset's files as this tool has them, which the uninstall removes.
-    let toolEntry;
-    try {
-        const lockfile = await readLockfile(projectDir);
-        lockedVersion = findInstalledAsset(lockfile, assetName, installed.type, installed.org)?.version;
-        const toolLockfile = options.toolLockfile ?? lockfile;
-        toolEntry = findInstalledAsset(toolLockfile, assetName, installed.type, installed.org) ?? installed;
-        snapshot = await snapshotFiles(updateTouchedPaths([lockfile, toolLockfile], plan, [installed, toolEntry], adapter, projectDir));
-    }
-    catch (snapshotError) {
-        throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${failureReason(snapshotError, installed)} ` +
-            `v${fromVersion} is still installed.`, errorGuidance(snapshotError));
-    }
-    let results;
-    try {
-        // Uninstall current version without cascade — new version may still need the same deps.
-        // The lockfile entry is kept so the reinstall below can carry over the config entries
-        // other tools registered for this asset (the install replaces the entry either way).
-        onProgress?.(`Removing ${assetName}@${fromVersion}...`);
-        await uninstallAsset(assetName, {
-            adapter,
-            cascade: false,
-            keepLockfileEntry: true,
-            ...(options.toolLockfile ? { managedFrom: options.toolLockfile } : {}),
-            onProgress,
-            org: installed.org,
-            plan: { dependents: [], orphanedDependencies: [], primary: toolEntry },
-            projectDir,
-            type: installed.type,
-        });
-        // Install target version (pass explicit version to resolver)
-        onProgress?.(`Installing ${assetName}@${toVersion}...`);
-        // Not forced: the paths this tool has are ATK-managed, so only an unmanaged file or another
-        // installed asset's file conflicts.
-        results = await executeInstallPlan(plan, {
-            adapter,
-            files,
-            ...(options.toolLockfile ? { managedFrom: options.toolLockfile } : {}),
-            onProgress,
-            projectDir,
-        });
-    }
-    catch (installError) {
-        // `atk update --force` overrides pins, not file conflicts, so the conflict gets its own advice.
-        const conflict = installError instanceof InstallPlanError && installError.cause instanceof FileConflictError
-            ? { asset: installError.asset, owner: installError.cause.owner, where: installError.cause.where }
-            : undefined;
-        const owner = conflict?.owner && formatOrgName(conflict.owner.org, conflict.owner.name);
-        const installFailure = conflict
-            ? `${conflict.where} ` +
-                (conflict.owner
-                    ? `belongs to the installed ${conflict.owner.type} "${owner}"`
-                    : 'already exists and was not installed by ATK') +
-                (isSameAsset(conflict.asset, installed)
-                    ? '.'
-                    : `, and the dependency "${formatOrgName(conflict.asset.org, conflict.asset.name)}" goes there.`)
-            : failureReason(installError, installed);
-        const conflictRemedy = owner ? `Uninstall "${owner}" first` : 'Move or rename it';
-        onProgress?.(`Update of ${assetName} to ${toVersion} failed, attempting to restore ${assetName}@${fromVersion}...`);
-        try {
-            await restoreFiles(snapshot);
-        }
-        catch (rollbackError) {
-            const rollbackFailure = failureReason(rollbackError, installed);
-            throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${installFailure} ` +
-                `Rollback to v${fromVersion} also failed` +
-                (rollbackFailure === installFailure ? ' for the same reason. ' : `: ${rollbackFailure} `) +
-                `Run "atk sync" to restore the asset.`, { command: 'atk sync', ...errorGuidance(installError) });
-        }
-        if (lockedVersion !== undefined && lockedVersion !== fromVersion) {
-            // The lockfile has one entry for every tool, so this tool's files now trail it.
-            const tool = adapter.tool;
-            const command = `atk sync --tool ${tool}`;
-            throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion} for ${tool}: ${installFailure} ` +
-                `Its ${tool} files were restored to v${fromVersion}, but the lockfile records v${lockedVersion}, ` +
-                `which the other tools have. Run "${command}" to install v${lockedVersion} for ${tool}.`, conflict
-                ? { command, hint: `${conflictRemedy}, then run the command.` }
-                : { ...errorGuidance(installError), command });
-        }
-        throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${installFailure} ` +
-            `The previous version (v${fromVersion}) has been restored.`, conflict ? { hint: `${conflictRemedy}, then run the update again.` } : errorGuidance(installError));
-    }
-    // After the restore path: the new version is installed, and restoring the old lockfile would
-    // orphan the files of the dependencies it added.
-    await restoreBundleOrigin(projectDir, installed);
-    // Match org and version too: the plan can hold a same-named dependency from another org.
-    const directResult = results.find((r) => r.name === assetName && r.type === installed.type && r.org === installed.org && r.version === toVersion);
-    if (!directResult) {
-        throw new UpdaterError(`Install did not produce a result for "${assetName}".`);
-    }
-    // Clean up dropped dependencies: deps in old version but not in new version. One asset's
-    // dependency refs carry no org, so type and name identify each.
-    const newDeps = resolved.versionData.dependencies ?? [];
-    const newDepKeys = new Set(newDeps.map((d) => `${d.type}:${d.name}`));
-    const droppedDeps = oldDeps.filter((d) => !newDepKeys.has(`${d.type}:${d.name}`));
-    // The new version is installed, so a cleanup failure is a warning, not a failed update.
-    const warnings = [];
-    if (droppedDeps.length > 0) {
-        // Read after the install: before it, the old entry still lists the dropped deps as its own.
-        const updatedLockfile = await readLockfile(projectDir);
-        for (const dep of droppedDeps) {
-            const depAsset = findDependencyAsset(updatedLockfile, dep, installed.org);
-            if (!depAsset)
-                continue;
-            // Only remove if it was a dependency and no other asset depends on it for this tool
-            if ((depAsset.installReason ?? 'direct') !== 'dependency')
-                continue;
-            const dependents = findDependents(updatedLockfile, depAsset.name, depAsset.type, depAsset.org).filter((d) => !isExcludedForTool(d, adapter.tool));
-            if (dependents.length === 0) {
-                onProgress?.(`Removing dropped dependency ${dep.name}...`);
-                try {
-                    await uninstallAsset(dep.name, {
-                        adapter,
-                        cascade: true,
-                        onProgress,
-                        org: depAsset.org,
-                        projectDir,
-                        toolScope: { configuredAdapters: options.configuredAdapters ?? [adapter] },
-                        type: depAsset.type,
-                    });
-                }
-                catch (error) {
-                    const message = `Could not remove dropped dependency "${dep.name}": ${asSentence(errorMessage(error))}`;
-                    onProgress?.(`Warning: ${message}`);
-                    // Other tools may still need the dependency, so the command removes it for this tool only.
-                    const toolFlag = (options.configuredAdapters?.length ?? 1) > 1 ? ` --tool ${adapter.tool}` : '';
-                    const spec = `${depAsset.org ? `@${depAsset.org}/` : ''}${dep.name}`;
-                    warnings.push({ command: `atk uninstall ${spec}${toolFlag}`, message });
-                }
-            }
-        }
-    }
-    return {
-        fromVersion,
-        installResult: directResult,
-        name: assetName,
-        ...(installed.org ? { org: installed.org } : {}),
-        toVersion,
-        type: installed.type,
-        ...(warnings.length > 0 ? { warnings } : {}),
-    };
+    return (await updateAssetPlanned(assetName, installed, registry, options)).result;
 }
 /**
  * Update multiple assets. If no names provided, updates all outdated assets.
@@ -323,14 +157,17 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
             reportUnsupported(installed, options);
             return { failures: [], results: [] };
         }
-        const dependencySkip = await failedDependencySkipFor(installed, registry, options);
+        if (!declarationAllowsVersion(registry, installed, options.targetVersion, options.adapter)) {
+            reportUndeclared(installed, options);
+            return { failures: [], results: [] };
+        }
+        // The skip check and the update plan from the same view of what this tool has.
+        const toolOptions = { ...options, toolLockfile: options.toolLockfile ?? lockfile };
+        const dependencySkip = await failedDependencySkipFor(installed, registry, toolOptions);
         if (dependencySkip) {
             return { failedSkipped: [dependencySkip], failures: [], results: [] };
         }
-        const result = await updateAsset(name, installed, registry, {
-            ...options,
-            toolLockfile: options.toolLockfile ?? lockfile,
-        });
+        const result = await updateAsset(name, installed, registry, toolOptions);
         return { failures: [], results: [result] };
     }
     const outdated = checkOutdated(lockfile, registry, options.frozenAssets);
@@ -408,6 +245,11 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
             reportUnsupported(asset, options);
             return false;
         }
+        // A hook whose new version doesn't declare the tool: the installer would refuse it.
+        if (!declarationAllowsVersion(registry, asset, asset.latestVersion, options.adapter)) {
+            reportUndeclared(asset, options);
+            return false;
+        }
         return true;
     });
     if (toUpdate.length === 0) {
@@ -434,14 +276,14 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
         if (!installed) {
             throw new UpdaterError(`Asset "${asset.name}" is installed but not found in lockfile.`);
         }
-        let result;
+        let updated;
         try {
-            const dependencySkip = await failedDependencySkipFor(installed, registry, options);
+            const dependencySkip = await failedDependencySkipFor(installed, registry, { ...options, toolLockfile });
             if (dependencySkip) {
                 failedSkipped.push(dependencySkip);
                 continue;
             }
-            result = await updateAsset(asset.name, installed, registry, { ...options, toolLockfile });
+            updated = await updateAssetPlanned(asset.name, installed, registry, { ...options, toolLockfile });
         }
         catch (error) {
             // Most errors from updateAsset already name the asset; only frame the ones that don't.
@@ -465,9 +307,10 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
             }
             continue;
         }
-        results.push(result);
-        // The update succeeded either way; a failed read leaves the next update to report it.
-        toolLockfile = await withInstalledEntries(toolLockfile, planFor(registry, installed, result.toVersion), options).catch(() => toolLockfile);
+        results.push(updated.result);
+        // The update succeeded either way; a failed read leaves the next update to report it. Only the
+        // assets it installed: a dependency it kept may hold another tool's entry on disk by now.
+        toolLockfile = await withInstalledEntries(toolLockfile, updated.plan, options).catch(() => toolLockfile);
     }
     return {
         ...(excludedSkipped.length > 0 ? { excludedSkipped } : {}),
@@ -487,7 +330,8 @@ function assetSpec(asset, type) {
  * The skip record for an asset whose update would move a dependency whose own update failed for
  * an earlier tool in the run: that tool kept the version the lockfile records, so moving it here
  * would leave the tools on different versions. A dependency the lockfile already records at the
- * plan's version, or one this tool has no placement for, is not moved, so it does not count.
+ * plan's version, one this tool has no placement for, or one the update keeps (see
+ * {@link withoutKeptDependencies}) is not moved, so it does not count.
  */
 async function failedDependencySkipFor(installed, registry, options) {
     if (!options.failedFor?.size)
@@ -497,7 +341,18 @@ async function failedDependencySkipFor(installed, registry, options) {
     if (!resolved || resolved.asset.org !== installed.org)
         return undefined;
     const lockfile = await readLockfile(options.projectDir);
-    for (const { asset, version } of planFor(registry, installed, resolved.version).entries) {
+    let plan;
+    try {
+        const { adapter, projectDir, toolLockfile } = options;
+        plan = planFor(registry, installed, resolved.version, { adapter, lockfile: toolLockfile ?? lockfile, projectDir });
+    }
+    catch (error) {
+        // It would move a pinned dependency, which the update itself refuses and reports.
+        if (error instanceof InstallerError)
+            return undefined;
+        throw error;
+    }
+    for (const { asset, version } of plan.entries) {
         if (isSameAsset(asset, installed) || !supportsType(options.adapter, asset.type))
             continue;
         const failedFor = options.failedFor.get(`${asset.type}:${asset.org ?? ''}:${asset.name}`);
@@ -559,9 +414,14 @@ function lockfileEntryFor(lockfile, asset) {
  * dependency must not turn it into a direct install. Only the requested asset's entry is
  * `direct`, so a same-named entry, such as a dependency of another type or org, keeps its
  * own reason.
+ *
+ * With `kept`, the dependencies that lockfile has in place for the adapter's tool at a version the
+ * plan accepts are left out (see {@link withoutKeptDependencies}). That runs before the reason is
+ * carried over, while the asset being updated is still the plan's one direct entry.
  */
-function planFor(registry, installed, version) {
-    const plan = resolveInstallPlan(registry, installed.name, installed.type, version, installed.org);
+function planFor(registry, installed, version, kept) {
+    const resolved = resolveInstallPlan(registry, installed.name, installed.type, version, installed.org);
+    const plan = kept ? withoutKeptDependencies(resolved, kept.lockfile, [{ adapter: kept.adapter }], kept) : resolved;
     const reason = installed.installReason ?? 'direct';
     return {
         ...plan,
@@ -572,6 +432,9 @@ function planFor(registry, installed, version) {
 async function recordedLockfile(options) {
     return options.failedFor?.size ? readLockfile(options.projectDir) : undefined;
 }
+function reportUndeclared(asset, options) {
+    options.onProgress?.(`Skipping ${asset.name}: the hook does not declare ${options.adapter.tool}`);
+}
 function reportUnsupported(asset, options) {
     options.onProgress?.(`Skipping ${asset.name}: ${options.adapter.tool} has no placement for ${asset.type} assets`);
 }
@@ -595,6 +458,202 @@ function scopeSwitchError(installed, fallback) {
 function toExcludedSkipped(installed) {
     return { name: installed.name, ...(installed.org ? { org: installed.org } : {}), type: installed.type };
 }
+/** {@link updateAsset}, with the plan it installed: kept dependencies are not in it. */
+async function updateAssetPlanned(assetName, installed, registry, options) {
+    const { adapter, onProgress, projectDir, targetVersion } = options;
+    // Resolve the target version — defaults to latest when targetVersion is undefined
+    const resolved = findAsset(registry, assetName, installed.type, targetVersion, installed.org);
+    if (!resolved) {
+        if (targetVersion) {
+            throw new UpdaterError(`Asset "${assetName}" version "${targetVersion}" not found in registry.`);
+        }
+        throw new UpdaterError(`Asset "${assetName}" not found in registry.`);
+    }
+    if (resolved.asset.org !== installed.org) {
+        throw scopeSwitchError(installed, resolved.asset);
+    }
+    const toVersion = resolved.version;
+    if (!isNewer(toVersion, installed.version)) {
+        if (targetVersion) {
+            throw new UpdaterError(`Asset "${assetName}" is already at or ahead of the requested version (installed: v${installed.version}, requested: v${toVersion}).`);
+        }
+        throw new UpdaterError(`Asset "${assetName}" is already at the latest version (v${installed.version}).`);
+    }
+    const fromVersion = installed.version;
+    // Capture old dependencies before uninstalling
+    const oldDeps = installed.dependencies ?? [];
+    // Dependencies this tool already has at a version the new one accepts stay as they are, as in
+    // `atk install`; moving a pinned one refuses the update before anything changes.
+    let plan;
+    try {
+        const kept = { ...options, lockfile: options.toolLockfile ?? (await readLockfile(projectDir)) };
+        plan = planFor(registry, installed, toVersion, kept);
+    }
+    catch (planError) {
+        throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${failureReason(planError, installed)} ` +
+            `v${fromVersion} is still installed.`, errorGuidance(planError));
+    }
+    // Download the target version before removing anything, so a refused download (an outdated
+    // CLI, an expired sign-in, the API down) leaves the installed version in place.
+    onProgress?.(`Downloading ${assetName}@${toVersion}...`);
+    let files;
+    try {
+        files = await fetchPlanFiles(plan, adapter);
+    }
+    catch (downloadError) {
+        throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${failureReason(downloadError, installed)} ` +
+            `v${fromVersion} is still installed.`, errorGuidance(downloadError));
+    }
+    // Capture what the update can change, so a failed uninstall or install restores it without the network.
+    let snapshot;
+    // The version the lockfile records now. In a multi-tool update an earlier tool may already
+    // have moved it past `fromVersion`, which a restore then puts back.
+    let lockedVersion;
+    // The asset's files as this tool has them, which the uninstall removes.
+    let toolEntry;
+    try {
+        const lockfile = await readLockfile(projectDir);
+        lockedVersion = findInstalledAsset(lockfile, assetName, installed.type, installed.org)?.version;
+        const toolLockfile = options.toolLockfile ?? lockfile;
+        toolEntry = findInstalledAsset(toolLockfile, assetName, installed.type, installed.org) ?? installed;
+        snapshot = await snapshotFiles(updateTouchedPaths([lockfile, toolLockfile], plan, [installed, toolEntry], adapter, projectDir));
+    }
+    catch (snapshotError) {
+        throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${failureReason(snapshotError, installed)} ` +
+            `v${fromVersion} is still installed.`, errorGuidance(snapshotError));
+    }
+    let results;
+    try {
+        // Uninstall current version without cascade — new version may still need the same deps.
+        // The lockfile entry is kept so the reinstall below can carry over the config entries
+        // other tools registered for this asset (the install replaces the entry either way).
+        onProgress?.(`Removing ${assetName}@${fromVersion}...`);
+        await uninstallAsset(assetName, {
+            adapter,
+            cascade: false,
+            keepLockfileEntry: true,
+            ...(options.toolLockfile ? { managedFrom: options.toolLockfile } : {}),
+            onProgress,
+            org: installed.org,
+            plan: { dependents: [], orphanedDependencies: [], primary: toolEntry },
+            projectDir,
+            type: installed.type,
+        });
+        // Install target version (pass explicit version to resolver)
+        onProgress?.(`Installing ${assetName}@${toVersion}...`);
+        // Not forced: the paths this tool has are ATK-managed, so only an unmanaged file or another
+        // installed asset's file conflicts.
+        results = await executeInstallPlan(plan, {
+            adapter,
+            files,
+            ...(options.toolLockfile ? { managedFrom: options.toolLockfile } : {}),
+            onProgress,
+            projectDir,
+        });
+    }
+    catch (installError) {
+        // `atk update --force` overrides pins, not file conflicts, so the conflict gets its own advice.
+        const conflict = installError instanceof InstallPlanError && installError.cause instanceof FileConflictError
+            ? { asset: installError.asset, owner: installError.cause.owner, where: installError.cause.where }
+            : undefined;
+        const owner = conflict?.owner && formatOrgName(conflict.owner.org, conflict.owner.name);
+        const installFailure = conflict
+            ? `${conflict.where} ` +
+                (conflict.owner
+                    ? `belongs to the installed ${conflict.owner.type} "${owner}"`
+                    : 'already exists and was not installed by ATK') +
+                (isSameAsset(conflict.asset, installed)
+                    ? '.'
+                    : `, and the dependency "${formatOrgName(conflict.asset.org, conflict.asset.name)}" goes there.`)
+            : failureReason(installError, installed);
+        const conflictRemedy = owner ? `Uninstall "${owner}" first` : 'Move or rename it';
+        onProgress?.(`Update of ${assetName} to ${toVersion} failed, attempting to restore ${assetName}@${fromVersion}...`);
+        try {
+            await restoreFiles(snapshot);
+        }
+        catch (rollbackError) {
+            const rollbackFailure = failureReason(rollbackError, installed);
+            throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${installFailure} ` +
+                `Rollback to v${fromVersion} also failed` +
+                (rollbackFailure === installFailure ? ' for the same reason. ' : `: ${rollbackFailure} `) +
+                `Run "atk sync" to restore the asset.`, { command: 'atk sync', ...errorGuidance(installError) });
+        }
+        if (lockedVersion !== undefined && lockedVersion !== fromVersion) {
+            // The lockfile has one entry for every tool, so this tool's files now trail it.
+            const tool = adapter.tool;
+            const command = `atk sync --tool ${tool}`;
+            throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion} for ${tool}: ${installFailure} ` +
+                `Its ${tool} files were restored to v${fromVersion}, but the lockfile records v${lockedVersion}, ` +
+                `which the other tools have. Run "${command}" to install v${lockedVersion} for ${tool}.`, conflict
+                ? { command, hint: `${conflictRemedy}, then run the command.` }
+                : { ...errorGuidance(installError), command });
+        }
+        throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${installFailure} ` +
+            `The previous version (v${fromVersion}) has been restored.`, conflict ? { hint: `${conflictRemedy}, then run the update again.` } : errorGuidance(installError));
+    }
+    // After the restore path: the new version is installed, and restoring the old lockfile would
+    // orphan the files of the dependencies it added.
+    await restoreBundleOrigin(projectDir, installed);
+    // Match org and version too: the plan can hold a same-named dependency from another org.
+    const directResult = results.find((r) => r.name === assetName && r.type === installed.type && r.org === installed.org && r.version === toVersion);
+    if (!directResult) {
+        throw new UpdaterError(`Install did not produce a result for "${assetName}".`);
+    }
+    // Clean up dropped dependencies: deps in old version but not in new version. One asset's
+    // dependency refs carry no org, so type and name identify each.
+    const newDeps = resolved.versionData.dependencies ?? [];
+    const newDepKeys = new Set(newDeps.map((d) => `${d.type}:${d.name}`));
+    const droppedDeps = oldDeps.filter((d) => !newDepKeys.has(`${d.type}:${d.name}`));
+    // The new version is installed, so a cleanup failure is a warning, not a failed update.
+    const warnings = [];
+    if (droppedDeps.length > 0) {
+        // Read after the install: before it, the old entry still lists the dropped deps as its own.
+        const updatedLockfile = await readLockfile(projectDir);
+        for (const dep of droppedDeps) {
+            const depAsset = findDependencyAsset(updatedLockfile, dep, installed.org);
+            if (!depAsset)
+                continue;
+            // Only remove if it was a dependency and no other asset depends on it for this tool
+            if ((depAsset.installReason ?? 'direct') !== 'dependency')
+                continue;
+            const dependents = findDependents(updatedLockfile, depAsset.name, depAsset.type, depAsset.org).filter((d) => !isExcludedForTool(d, adapter.tool));
+            if (dependents.length === 0) {
+                onProgress?.(`Removing dropped dependency ${dep.name}...`);
+                try {
+                    await uninstallAsset(dep.name, {
+                        adapter,
+                        cascade: true,
+                        onProgress,
+                        org: depAsset.org,
+                        projectDir,
+                        toolScope: { configuredAdapters: options.configuredAdapters ?? [adapter] },
+                        type: depAsset.type,
+                    });
+                }
+                catch (error) {
+                    const message = `Could not remove dropped dependency "${dep.name}": ${asSentence(errorMessage(error))}`;
+                    onProgress?.(`Warning: ${message}`);
+                    // Other tools may still need the dependency, so the command removes it for this tool only.
+                    const toolFlag = (options.configuredAdapters?.length ?? 1) > 1 ? ` --tool ${adapter.tool}` : '';
+                    const spec = `${depAsset.org ? `@${depAsset.org}/` : ''}${dep.name}`;
+                    warnings.push({ command: `atk uninstall ${spec}${toolFlag}`, message });
+                }
+            }
+        }
+    }
+    return {
+        plan,
+        result: {
+            fromVersion,
+            installResult: directResult,
+            name: assetName,
+            ...(installed.org ? { org: installed.org } : {}),
+            toVersion,
+            type: installed.type,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        },
+    };
+}
 /**
  * The absolute paths that updating `installed` with `plan` can change for the adapter's tool:
  * the lockfile, the placed files and config files of the asset and of every installed asset the