@detergent-software/atk 8.1.2-dev.9 → 8.1.3-dev.1

package/build/lib/updater.js

@@ -1,9 +1,14 @@
+import { join } from 'node:path';
 import { compare, valid } from 'semver';
-import { isExcludedForTool } from './asset-tools.js';
+import { getPlacement, resolveInstalledPaths } from './adapter.js';
+import { 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 { executeInstallPlan } from './installer.js';
-import { addAssetToLockfile, findDependents, findInstalledAsset, readLockfile, writeLockfile } from './lockfile.js';
+import { restoreFiles, snapshotFiles } from './file-snapshot.js';
+import { executeInstallPlan, fetchPlanFiles, FileConflictError, installFailureMessage, InstallPlanError, } from './installer.js';
+import { addAssetToLockfile, findDependencyAsset, findDependents, findInstalledAsset, getLockfilePath, readLockfile, writeLockfile, } from './lockfile.js';
+import { formatOrgName, parseOrgFromName, scopeSwitchGuidance } from './org.js';
 import { findAsset } from './registry.js';
 import { resolveInstallPlan } from './resolver.js';
 import { uninstallAsset } from './uninstaller.js';
@@ -19,8 +24,9 @@ export function checkOutdated(lockfile, registry, frozenNames) {
     const outdated = [];
     for (const installed of lockfile.assets ?? []) {
         const resolved = findAsset(registry, installed.name, installed.type, undefined, installed.org);
-        if (!resolved) {
-            // Asset no longer in registry — skip (could be removed/deprecated)
+        if (!resolved || resolved.asset.org !== installed.org) {
+            // Asset no longer in registry — skip (could be removed/deprecated). For an org asset the
+            // lookup falls back to the global asset of the same name, which update does not switch to.
             continue;
         }
         // resolved.version is the latest version (findAsset defaults to latest)
@@ -39,9 +45,38 @@ export function checkOutdated(lockfile, registry, frozenNames) {
     }
     return outdated;
 }
+/**
+ * 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
+ * one. A name installed as more than one type needs `type` to pick one.
+ */
+export function findUpdateTarget(lockfile, spec, { type, version } = {}) {
+    const { name, org } = parseOrgFromName(spec);
+    const named = (lockfile.assets ?? []).filter((a) => a.name === name && (!type || a.type === type));
+    let matches = named.filter((a) => a.org === (org ?? lockfile.org));
+    if (matches.length === 0 && !org && lockfile.org) {
+        matches = named.filter((a) => a.org === undefined);
+    }
+    const versionSuffix = version ? `@${version}` : '';
+    if (matches.length > 1) {
+        const types = matches.map((a) => a.type).sort();
+        throw new UpdaterError(`"${spec}" is installed as more than one type (${types.join(', ')}). Name the one to update with --type.`, { command: `atk update ${spec}${versionSuffix} --type ${types[0]}` });
+    }
+    if (matches.length === 1)
+        return matches[0];
+    const elsewhere = [...new Set(named.map((a) => formatOrgName(a.org, a.name)))].sort();
+    if (elsewhere.length > 0) {
+        throw new UpdaterError(`Asset "${spec}" is not installed. Installed as: ${elsewhere.join(', ')}.`, elsewhere.length === 1
+            ? { command: `atk update ${elsewhere[0]}${versionSuffix}${type ? ` --type ${type}` : ''}` }
+            : {});
+    }
+    throw new UpdaterError(`Asset "${spec}" is not installed.`);
+}
 /**
  * Update a single asset to the target version (defaults to latest).
- * Uninstalls the current version and installs the target from registry.
+ * Downloads the target version, then uninstalls the current version and installs the target.
+ * A failed uninstall or install puts back the files the update changed, from a snapshot taken after the
+ * download, so the rollback needs no second download.
  */
 export async function updateAsset(assetName, installed, registry, options) {
     const { adapter, onProgress, projectDir, targetVersion } = options;
@@ -53,6 +88,9 @@ export async function updateAsset(assetName, installed, registry, options) {
         }
         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) {
@@ -63,71 +101,152 @@ export async function updateAsset(assetName, installed, registry, options) {
     const fromVersion = installed.version;
     // Capture old dependencies before uninstalling
     const oldDeps = installed.dependencies ?? [];
-    // 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,
-        onProgress,
-        org: installed.org,
-        projectDir,
-    });
-    // Install target version (pass explicit version to resolver)
-    onProgress?.(`Installing ${assetName}@${toVersion}...`);
+    // 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 {
-        results = await executeInstallPlan(planFor(registry, installed, toVersion), {
+        // 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,
-            force: true,
+            files,
+            ...(options.toolLockfile ? { managedFrom: options.toolLockfile } : {}),
             onProgress,
             projectDir,
         });
-        await restoreBundleOrigin(projectDir, installed);
     }
     catch (installError) {
-        // Install failed — attempt to rollback by re-installing the old version
-        onProgress?.(`Install of ${assetName}@${toVersion} failed, attempting to restore ${assetName}@${fromVersion}...`);
+        // `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 executeInstallPlan(planFor(registry, installed, fromVersion), {
-                adapter,
-                force: true,
-                onProgress,
-                projectDir,
-            });
-            await restoreBundleOrigin(projectDir, installed);
+            await restoreFiles(snapshot);
         }
         catch (rollbackError) {
-            throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${asSentence(errorMessage(installError))} ` +
-                `Rollback to v${fromVersion} also failed: ${asSentence(errorMessage(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) });
         }
-        throw new UpdaterError(`Failed to update "${assetName}" to v${toVersion}: ${asSentence(errorMessage(installError))} ` +
-            `The previous version (v${fromVersion}) has been restored.`, 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));
     }
-    const directResult = results.find((r) => r.name === assetName);
+    // 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
+    // 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) {
-        const updatedLockfile = options.lockfile ?? (await readLockfile(projectDir));
+        // 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 = findInstalledAsset(updatedLockfile, dep.name, dep.type, dep.org);
+            const depAsset = findDependencyAsset(updatedLockfile, dep, installed.org);
             if (!depAsset)
                 continue;
-            // Only remove if it was a dependency and no other asset depends on it
+            // 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, dep.name, dep.type);
+            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}...`);
-                await uninstallAsset(dep.name, { adapter, cascade: true, onProgress, org: dep.org, projectDir });
+                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 });
+                }
             }
         }
     }
@@ -135,8 +254,10 @@ export async function updateAsset(assetName, installed, registry, options) {
         fromVersion,
         installResult: directResult,
         name: assetName,
+        ...(installed.org ? { org: installed.org } : {}),
         toVersion,
         type: installed.type,
+        ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
 /**
@@ -148,23 +269,24 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
     // When a specific target version is requested for a single asset, bypass outdated check
     // and delegate directly to updateAsset which handles version comparison.
     if (options.targetVersion && assetNames && assetNames.length === 1) {
-        const name = assetNames[0];
-        const installed = (lockfile.assets ?? []).find((a) => a.name === name);
-        if (!installed) {
-            throw new UpdaterError(`Asset "${name}" is not installed.`);
-        }
+        const installed = findUpdateTarget(lockfile, assetNames[0], {
+            type: options.type,
+            version: options.targetVersion,
+        });
+        const { name } = installed;
+        const spec = assetSpec(installed, options.type);
         // Check frozen state for explicitly targeted asset
         const compositeKey = `${installed.type}:${installed.org ?? ''}:${name}`;
         if (options.frozenAssets?.has(compositeKey)) {
-            throw new UpdaterError(`Asset "${name}" is frozen. Use "atk thaw ${name}" to unfreeze it before updating.`, {
-                command: `atk thaw ${name}`,
+            throw new UpdaterError(`Asset "${name}" is frozen. Use "atk thaw ${spec}" to unfreeze it before updating.`, {
+                command: `atk thaw ${spec}`,
                 hint: 'Thaw the asset before updating, or remove it from your lockfile.',
             });
         }
         // Check pin state for explicitly targeted asset
         if (installed.pinnedVersion && !options.force) {
             throw new UpdaterError(`Asset "${name}" is pinned to version "${installed.pinnedVersion}". Use --force to override the pin.`, {
-                command: `atk unpin ${name}`,
+                command: `atk unpin ${spec}`,
                 hint: 'Unpin the asset, or pass --force to override the pin.',
             });
         }
@@ -174,10 +296,21 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
             options.onProgress?.(`Skipping ${name}: uninstalled for ${options.adapter.tool}`);
             return { excludedSkipped: [toExcludedSkipped(installed)], failures: [], results: [] };
         }
-        const currentLockfile = await readLockfile(options.projectDir);
+        const failedSkip = failedSkipFor(installed, lockfile, await recordedLockfile(options), options);
+        if (failedSkip) {
+            return { failedSkipped: [failedSkip], failures: [], results: [] };
+        }
+        if (!supportsType(options.adapter, installed.type)) {
+            reportUnsupported(installed, options);
+            return { failures: [], results: [] };
+        }
+        const dependencySkip = await failedDependencySkipFor(installed, registry, options);
+        if (dependencySkip) {
+            return { failedSkipped: [dependencySkip], failures: [], results: [] };
+        }
         const result = await updateAsset(name, installed, registry, {
             ...options,
-            lockfile: currentLockfile,
+            toolLockfile: options.toolLockfile ?? lockfile,
         });
         return { failures: [], results: [result] };
     }
@@ -186,22 +319,24 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
     const frozenSkipped = [];
     const skipped = [];
     if (assetNames && assetNames.length > 0) {
-        toUpdate = outdated.filter((o) => assetNames.includes(o.name));
+        const targets = assetNames.map((spec) => findUpdateTarget(lockfile, spec, { type: options.type }));
+        toUpdate = outdated.filter((o) => targets.some((t) => isSameAsset(t, o)));
         // Check for names that aren't outdated
-        for (const name of assetNames) {
-            if (!outdated.find((o) => o.name === name)) {
-                const installed = (lockfile.assets ?? []).find((a) => a.name === name);
-                if (!installed) {
-                    throw new UpdaterError(`Asset "${name}" is not installed.`);
+        for (const target of targets) {
+            if (!outdated.some((o) => isSameAsset(target, o))) {
+                const resolved = findAsset(registry, target.name, target.type, undefined, target.org);
+                if (resolved && resolved.asset.org !== target.org) {
+                    throw scopeSwitchError(target, resolved.asset);
                 }
-                throw new UpdaterError(`Asset "${name}" is already at the latest version (v${installed.version}).`);
+                throw new UpdaterError(`Asset "${formatOrgName(target.org, target.name)}" is already at the latest version (v${target.version}).`);
             }
         }
         // For explicitly targeted frozen assets, throw
         for (const asset of toUpdate) {
             if (asset.frozen) {
-                throw new UpdaterError(`Asset "${asset.name}" is frozen. Use "atk thaw ${asset.name}" to unfreeze it before updating.`, {
-                    command: `atk thaw ${asset.name}`,
+                const spec = assetSpec(asset, options.type);
+                throw new UpdaterError(`Asset "${asset.name}" is frozen. Use "atk thaw ${spec}" to unfreeze it before updating.`, {
+                    command: `atk thaw ${spec}`,
                     hint: 'Thaw the asset before updating, or remove it from your lockfile.',
                 });
             }
@@ -210,7 +345,7 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
         for (const asset of toUpdate) {
             if (asset.pinned && !options.force) {
                 throw new UpdaterError(`Asset "${asset.name}" is pinned. Use --force to override the pin.`, {
-                    command: `atk unpin ${asset.name}`,
+                    command: `atk unpin ${assetSpec(asset, options.type)}`,
                     hint: 'Unpin the asset, or pass --force to override the pin.',
                 });
             }
@@ -235,45 +370,59 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
     }
     // Assets uninstalled for this tool are never updated for it (that would reinstall them).
     const excludedSkipped = [];
+    const failedSkipped = [];
+    const recorded = await recordedLockfile(options);
     toUpdate = toUpdate.filter((asset) => {
-        const installed = (lockfile.assets ?? []).find((a) => a.name === asset.name && a.type === asset.type && a.org === asset.org);
+        const installed = lockfileEntryFor(lockfile, asset);
         if (installed && isExcludedForTool(installed, options.adapter.tool)) {
             options.onProgress?.(`Skipping ${asset.name}: uninstalled for ${options.adapter.tool}`);
             excludedSkipped.push(toExcludedSkipped(installed));
             return false;
         }
+        const failedSkip = failedSkipFor(asset, lockfile, recorded, options);
+        if (failedSkip) {
+            failedSkipped.push(failedSkip);
+            return false;
+        }
+        // The tool has no placement for the type (a rule under Codex CLI): nothing to update.
+        if (!supportsType(options.adapter, asset.type)) {
+            reportUnsupported(asset, options);
+            return false;
+        }
         return true;
     });
     if (toUpdate.length === 0) {
         return {
             ...(excludedSkipped.length > 0 ? { excludedSkipped } : {}),
+            ...(failedSkipped.length > 0 ? { failedSkipped } : {}),
             failures: [],
             frozenSkipped: frozenSkipped.length > 0 ? frozenSkipped : undefined,
             results: [],
             skipped: skipped.length > 0 ? skipped : undefined,
         };
     }
-    // Resolve the credential before removing anything. A missing or expired sign-in carries no
-    // API code for isRunWideFailure, and with a fresh registry cache it would otherwise first
-    // surface at each asset's download, after that asset's files were removed.
+    // Resolve the credential once, up front. A missing or expired sign-in carries no API code for
+    // isRunWideFailure, and with a fresh registry cache it would otherwise fail each asset's
+    // download in turn.
     await getCredential();
     const results = [];
     const failures = [];
     let notAttempted;
+    // What this tool has: the lockfile the run started from, plus what this tool's updates install.
+    let toolLockfile = options.toolLockfile ?? lockfile;
     for (const [index, asset] of toUpdate.entries()) {
-        const installed = (lockfile.assets ?? []).find((a) => a.name === asset.name);
+        const installed = lockfileEntryFor(lockfile, asset);
         if (!installed) {
             throw new UpdaterError(`Asset "${asset.name}" is installed but not found in lockfile.`);
         }
+        let result;
         try {
-            // Read the lockfile once per iteration for dropped dependency cleanup,
-            // rather than letting each updateAsset call re-read it internally.
-            const currentLockfile = await readLockfile(options.projectDir);
-            const result = await updateAsset(asset.name, installed, registry, {
-                ...options,
-                lockfile: currentLockfile,
-            });
-            results.push(result);
+            const dependencySkip = await failedDependencySkipFor(installed, registry, options);
+            if (dependencySkip) {
+                failedSkipped.push(dependencySkip);
+                continue;
+            }
+            result = await updateAsset(asset.name, installed, registry, { ...options, toolLockfile });
         }
         catch (error) {
             // Most errors from updateAsset already name the asset; only frame the ones that don't.
@@ -283,16 +432,27 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
                 : `Failed to update "${asset.name}": ${asSentence(cause)}`;
             options.onProgress?.(message);
             const guidance = errorGuidance(error);
-            failures.push({ error: message, name: asset.name, type: asset.type, ...guidance });
-            // The same error would fail every remaining asset, after removing its files first.
+            failures.push({
+                error: message,
+                name: asset.name,
+                ...(asset.org ? { org: asset.org } : {}),
+                type: asset.type,
+                ...guidance,
+            });
+            // The same error would fail every remaining asset.
             if (isRunWideFailure(guidance)) {
                 notAttempted = toUpdate.slice(index + 1).map((a) => a.name);
                 break;
             }
+            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);
     }
     return {
         ...(excludedSkipped.length > 0 ? { excludedSkipped } : {}),
+        ...(failedSkipped.length > 0 ? { failedSkipped } : {}),
         failures,
         frozenSkipped: frozenSkipped.length > 0 ? frozenSkipped : undefined,
         ...(notAttempted ? { notAttempted } : {}),
@@ -300,6 +460,60 @@ export async function updateAssets(assetNames, lockfile, registry, options) {
         skipped: skipped.length > 0 ? skipped : undefined,
     };
 }
+/** How a command names an asset: `@org/name`, with `--type` when the run was given one. */
+function assetSpec(asset, type) {
+    return `${formatOrgName(asset.org, asset.name)}${type ? ` --type ${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.
+ */
+async function failedDependencySkipFor(installed, registry, options) {
+    if (!options.failedFor?.size)
+        return undefined;
+    // An asset that does not resolve gets its error from the update itself.
+    const resolved = findAsset(registry, installed.name, installed.type, options.targetVersion, installed.org);
+    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) {
+        if (isSameAsset(asset, installed) || !supportsType(options.adapter, asset.type))
+            continue;
+        const failedFor = options.failedFor.get(`${asset.type}:${asset.org ?? ''}:${asset.name}`);
+        if (!failedFor || findInstalledAsset(lockfile, asset.name, asset.type, asset.org)?.version === version)
+            continue;
+        options.onProgress?.(`Skipping ${installed.name} for ${options.adapter.tool}: its dependency ${asset.name} failed to update for ${failedFor}`);
+        return {
+            dependency: { name: asset.name, ...(asset.org ? { org: asset.org } : {}), type: asset.type },
+            failedFor,
+            name: installed.name,
+            ...(installed.org ? { org: installed.org } : {}),
+            type: installed.type,
+        };
+    }
+    return undefined;
+}
+/**
+ * The skip record for an asset whose update failed for an earlier tool in the run, if it did. An
+ * asset that another asset's plan moved for that tool after all (the lockfile no longer records
+ * the run's starting version) is not skipped: the later tools move it too.
+ */
+function failedSkipFor(asset, snapshot, recorded, options) {
+    const failedFor = options.failedFor?.get(`${asset.type}:${asset.org ?? ''}:${asset.name}`);
+    if (!failedFor)
+        return undefined;
+    const versionIn = (lockfile) => lockfile && findInstalledAsset(lockfile, asset.name, asset.type, asset.org)?.version;
+    if (versionIn(recorded) !== versionIn(snapshot))
+        return undefined;
+    options.onProgress?.(`Skipping ${asset.name} for ${options.adapter.tool}: its update failed for ${failedFor}`);
+    return { failedFor, name: asset.name, ...(asset.org ? { org: asset.org } : {}), type: asset.type };
+}
+/** Why an install for an update failed, as a sentence; the update message already names the asset. */
+function failureReason(error, installed) {
+    return asSentence(installFailureMessage(error, installed));
+}
 /**
  * Check if the registry version is newer than the installed version.
  * Falls back to string comparison if semver parsing fails.
@@ -313,19 +527,35 @@ function isNewer(registryVersion, installedVersion) {
     // silently ignored.
     return registryVersion !== installedVersion;
 }
+function isSameAsset(a, b) {
+    return a.name === b.name && a.type === b.type && a.org === b.org;
+}
+/** The lockfile entry of an outdated asset: same name, type and org. */
+function lockfileEntryFor(lockfile, asset) {
+    return (lockfile.assets ?? []).find((a) => isSameAsset(a, asset));
+}
 /**
  * The install plan for one version of an installed asset. The resolver treats the asset as
  * a fresh top-level request, so keep the install reason its lockfile entry had: updating a
- * dependency must not turn it into a direct install.
+ * 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.
  */
 function planFor(registry, installed, version) {
     const plan = resolveInstallPlan(registry, installed.name, installed.type, version, installed.org);
     const reason = installed.installReason ?? 'direct';
     return {
         ...plan,
-        entries: plan.entries.map((e) => e.asset.name === installed.name && e.asset.type === installed.type ? { ...e, reason } : e),
+        entries: plan.entries.map((e) => (e.reason === 'direct' ? { ...e, reason } : e)),
     };
 }
+/** The lockfile on disk, read only when an earlier tool in the run had a failed update. */
+async function recordedLockfile(options) {
+    return options.failedFor?.size ? readLockfile(options.projectDir) : undefined;
+}
+function reportUnsupported(asset, options) {
+    options.onProgress?.(`Skipping ${asset.name}: ${options.adapter.tool} has no placement for ${asset.type} assets`);
+}
 /**
  * Put a bundle member's bundle origin back on its updated lockfile entry. Passing it to
  * executeInstallPlan would also stamp the asset's dependencies, so it is set here instead.
@@ -339,7 +569,50 @@ async function restoreBundleOrigin(projectDir, installed) {
         return;
     await writeLockfile(projectDir, addAssetToLockfile(lockfile, { ...entry, bundleOrigin: installed.bundleOrigin }));
 }
+function scopeSwitchError(installed, fallback) {
+    const { message, ...guidance } = scopeSwitchGuidance(installed, fallback, 'update');
+    return new UpdaterError(message, guidance);
+}
 function toExcludedSkipped(installed) {
     return { name: installed.name, ...(installed.org ? { org: installed.org } : {}), type: installed.type };
 }
+/**
+ * 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
+ * plan replaces (its dependencies), and the config files the plan's new assets register in. Each
+ * entry of `installed` and each lockfile of `lockfiles` is a view of what is installed; all count.
+ */
+function updateTouchedPaths(lockfiles, plan, installed, adapter, projectDir) {
+    const relativePaths = [];
+    const replaced = lockfiles.flatMap((lockfile) => plan.entries.flatMap((e) => findInstalledAsset(lockfile, e.asset.name, e.asset.type, e.asset.org) ?? []));
+    for (const asset of [...installed, ...replaced]) {
+        const resolved = resolveInstalledPaths(asset, adapter, projectDir);
+        relativePaths.push(...resolved.files.map((f) => f.installedPath));
+        relativePaths.push(...[...getConfigEntriesForTool(asset, adapter), ...resolved.configEntries].map((e) => e.file));
+    }
+    for (const { asset } of plan.entries) {
+        const placement = getPlacement(adapter, asset.type);
+        if (!placement)
+            continue;
+        if (placement.configFile)
+            relativePaths.push(placement.configFile);
+        if (placement.enabledListFile)
+            relativePaths.push(placement.enabledListFile);
+        // A memory template is spliced into a shared file at its placement path.
+        if (asset.type === 'memory-template')
+            relativePaths.push(placement.path.replace(/\{name\}/g, asset.name));
+    }
+    return [getLockfilePath(projectDir), ...relativePaths.map((p) => join(projectDir, p))];
+}
+/** `toolLockfile` with the on-disk lockfile entries of the assets an update installed with `plan`. */
+async function withInstalledEntries(toolLockfile, plan, { projectDir }) {
+    const lockfile = await readLockfile(projectDir);
+    let updated = toolLockfile;
+    for (const { asset } of plan.entries) {
+        const entry = findInstalledAsset(lockfile, asset.name, asset.type, asset.org);
+        if (entry)
+            updated = addAssetToLockfile(updated, entry);
+    }
+    return updated;
+}
 //# sourceMappingURL=updater.js.map