@detergent-software/atk 8.1.2-dev.4 → 8.1.2-dev.41

package/build/lib/installer.js

@@ -2,21 +2,73 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, unlink } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { getPlacement, isEntrypoint, resolveInstalledPaths } from './adapter.js';
-import { carryExcludedTools } from './asset-tools.js';
+import { carryExcludedTools, isExcludedForTool } from './asset-tools.js';
 import { computeConfigEntryChecksum, computeHookGroupChecksum, hashBytes } from './checksum.js';
-import { mergeConfigEntriesForTool } from './config-entries.js';
-import { detectConfigFormat, normalizeForFormat, readConfigFile, resolveConfigFormat, writeConfigFile, } from './config-file.js';
-import { ApiCodeError, errorGuidance } from './errors.js';
+import { getConfigEntriesForTool, getOtherToolsConfigEntries, mergeConfigEntriesForTool, normalizeConfigPath, } from './config-entries.js';
+import { normalizeForFormat, readConfigFile, resolveConfigFormat, writeConfigFile, } from './config-file.js';
+import { addToEnabledList, removeFromEnabledList } from './enabled-list.js';
+import { ApiCodeError, errorGuidance, errorMessage } from './errors.js';
 import { ensureGitignoreEntries } from './gitignore.js';
 import { buildHookGroup, deriveHookCommand, hookGroupOwnsCommand, removeHookGroup } from './hook-config.js';
 import { hookScriptPath, makeExecutable } from './hook-script.js';
-import { addAssetToLockfile, readLockfile, removeAssetFromLockfile, writeLockfile } from './lockfile.js';
+import { isInstalledForTool } from './installed-for-tool.js';
+import { addAssetToLockfile, findInstalledAsset, readLockfile, removeAssetFromLockfile, writeLockfile, } from './lockfile.js';
+import { formatOrgName } from './org.js';
+import { configEntriesOwnedByOthers, holdsAnotherOwnersValue, pathsOwnedByOthers } from './owned-paths.js';
 import { toRelativePosix } from './paths.js';
 import { fetchAssetFileBytes, fetchAssetManifest, listAssetFiles } from './registry.js';
 import { writeBinaryFile, writeTextFile } from './write-file.js';
 export class InstallerError extends ApiCodeError {
     name = 'InstallerError';
 }
+/**
+ * A file the install would place at `path` exists and is not ATK-managed, or belongs to `owner`,
+ * another installed asset; nothing was written there. With `entry`, the conflict is that part of
+ * the file (a memory-template's block, a config entry), which `owner` wrote.
+ */
+export class FileConflictError extends InstallerError {
+    name = 'FileConflictError';
+    owner;
+    path;
+    /** What conflicts, quoted for a message: `"<path>"`, or `the <entry> in "<path>"`. */
+    where;
+    constructor(path, owner, entry) {
+        const where = entry ? `the ${entry} in "${path}"` : `"${path}"`;
+        super(owner
+            ? `File conflict: ${where} belongs to the installed ${owner.type} "${formatOrgName(owner.org, owner.name)}".`
+            : `File conflict: ${where} already exists and was not installed by ATK. Use --force to overwrite.`, owner ? { hint: 'Uninstall it first if you want this one instead.' } : {});
+        this.owner = owner;
+        this.path = path;
+        this.where = where;
+    }
+}
+/**
+ * An install plan that failed at `asset` with `cause`, after rolling back the
+ * `rolledBack` assets it had already installed. Keeps the cause's API code and
+ * guidance, so callers that name the asset themselves can quote just the cause.
+ */
+export class InstallPlanError extends InstallerError {
+    asset;
+    cause;
+    /** The plan kept what it installed before `asset`, because it moved an installed asset to another version. */
+    keptInstall;
+    name = 'InstallPlanError';
+    constructor(asset, cause, rolledBack, keptInstall = false) {
+        const rollback = rolledBack > 0 ? ` and ${rolledBack} previously installed asset(s) were rolled back` : '';
+        super(`Install failed at asset "${formatOrgName(asset.org, asset.name)}"${rollback}: ${errorMessage(cause)}`, errorGuidance(cause));
+        this.asset = asset;
+        this.cause = cause;
+        this.keptInstall = keptInstall;
+    }
+}
+/** A plan whose files for `asset` could not be downloaded; nothing was written. */
+export class PlanDownloadError extends InstallPlanError {
+    name = 'PlanDownloadError';
+    constructor(asset, cause) {
+        super(asset, cause, 0);
+        this.message = `Download failed for asset "${formatOrgName(asset.org, asset.name)}": ${errorMessage(cause)}`;
+    }
+}
 /**
  * Guard for multi-tool installs run with `skipUnsupported`. Each tool skips the asset
  * types it cannot place, which is fine as long as some tool placed something. If every
@@ -36,9 +88,13 @@ export function assertInstalledByAnyTool(plan, toolResults) {
 }
 /**
  * Execute a full install plan — install all assets in order.
- * On partial failure, rolls back previously installed assets (deletes placed files,
- * reverts config entries, removes lockfile entries) so the system is not left in
- * an inconsistent state.
+ * On partial failure, deletes the files the failing asset wrote where no file was before placing
+ * its files failed, and rolls back the assets the plan added before it (deletes placed files,
+ * reverts config entries and memory-template blocks, removes lockfile entries) so the system is not
+ * left in an inconsistent state. An asset the tool already had in place keeps what the plan placed,
+ * since rolling it back would delete its working copy, and gets its lockfile entry back. When the
+ * plan moved such an asset to another version, which may need the assets the plan added, nothing is
+ * rolled back ({@link InstallPlanError.keptInstall}).
  */
 export async function executeInstallPlan(plan, options) {
     const results = [];
@@ -52,152 +108,339 @@ export async function executeInstallPlan(plan, options) {
     // Read lockfile once — used for both conflict detection and per-asset install logic
     let lockfile = await readLockfile(options.projectDir);
     const initialLockfile = lockfile;
-    // Build set of ATK-managed file paths from the lockfile for conflict detection
-    const managedPaths = buildManagedPathsSet(lockfile, options.projectDir, options.adapter);
+    // Map each ATK-managed file path to the assets that installed it, for conflict detection
+    const managedPaths = buildManagedPaths(options.managedFrom ?? lockfile, options.projectDir, options.adapter);
+    // ...and each block or keyed config entry to the assets that wrote it
+    const managedEntries = buildManagedEntries(options.managedFrom ?? lockfile, options.projectDir, options.adapter);
+    // ...and each keyed config entry of other tools to its owners, who may share it for this tool
+    const ownersElsewhere = buildEntryOwnersElsewhere(options.managedFrom ?? lockfile, options.adapter);
     // In multi-tool projects the same plan runs once per tool. A tool that has no
     // placement for an asset type (e.g. Codex CLI has no `rule` placement) skips
     // those entries instead of aborting the whole run for that tool. When the tool
     // supports nothing in the plan, fail loudly so a single-tool install isn't a
     // silent no-op.
-    const supportedEntries = [];
+    const supportedEntries = placeableEntries(plan, options.adapter);
     for (const entry of plan.entries) {
-        if (getPlacement(options.adapter, entry.asset.type)) {
-            supportedEntries.push(entry);
-        }
-        else {
+        if (!getPlacement(options.adapter, entry.asset.type)) {
             options.onProgress?.(`Skipping ${entry.asset.name}: ${options.adapter.displayName} does not support ${entry.asset.type} assets`);
         }
     }
     if (supportedEntries.length === 0 && plan.entries.length > 0 && !options.skipUnsupported) {
         throw new InstallerError(`Tool "${options.adapter.tool}" does not support asset type "${plan.entries[0].asset.type}"`);
     }
+    // The assets this tool had in place before the plan, by plan entry, which a failure keeps.
+    const installedBefore = options.installedBefore ?? options.managedFrom ?? lockfile;
+    const inPlace = new Map();
+    for (const entry of supportedEntries) {
+        const installed = findInstalledAsset(installedBefore, entry.asset.name, entry.asset.type, entry.asset.org);
+        if (installed && isInstalledForTool(installed, options.adapter, options.projectDir))
+            inPlace.set(entry, installed);
+    }
+    // The files the asset being placed wrote where no file was, which a failure removes.
+    let created = [];
     try {
         for (const entry of supportedEntries) {
-            const { lockfile: updatedLockfile, result } = await installAsset(entry, options, managedPaths, lockfile);
+            created = [];
+            const { lockfile: updatedLockfile, result, sharedEntries, } = await installAsset(entry, options, managedPaths, managedEntries, ownersElsewhere, lockfile, created);
             results.push(result);
+            // A later entry of this plan may land on these files or entries, and must see whose they are.
+            for (const file of result.filesPlaced)
+                addOwner(managedPaths, file.destination, entry.asset);
+            for (const shared of sharedEntries)
+                addOwner(managedEntries, sharedEntryKey(shared), entry.asset);
             lockfile = updatedLockfile;
         }
     }
     catch (error) {
-        // Roll back all successfully installed assets in reverse order
-        if (results.length > 0) {
-            options.onProgress?.(`Install failed, rolling back ${results.length} installed asset(s)...`);
-            for (let i = results.length - 1; i >= 0; i--) {
-                const result = results[i];
-                options.onProgress?.(`Rolling back ${result.name}...`);
-                // Delete placed files (best-effort)
-                for (const file of result.filesPlaced) {
-                    try {
-                        if (existsSync(file.destination)) {
-                            await unlink(file.destination);
-                        }
-                    }
-                    catch (error) {
-                        options.onProgress?.(`Warning: Failed to delete file during rollback: ${file.destination} — ${error instanceof Error ? error.message : String(error)}`);
-                    }
-                }
-                // Revert config file entries (best-effort)
-                for (const entry of result.configEntriesCreated) {
-                    try {
-                        const configPath = join(options.projectDir, entry.file);
-                        const format = resolveConfigFormat(configPath, getPlacement(options.adapter, result.type));
-                        await revertConfigEntry(configPath, entry.key, entry.command, format, options.onProgress);
-                    }
-                    catch (error) {
-                        options.onProgress?.(`Warning: Failed to revert config entry ${entry.key} during rollback — ${error instanceof Error ? error.message : String(error)}`);
-                    }
-                }
-                // Revert the lockfile entry using the in-memory lockfile (best-effort). An asset that
-                // was already recorded before this plan ran (a sync/update reinstall, or a second
-                // tool's pass in a multi-tool install) gets its previous entry back, so other tools'
-                // config entries survive; a newly added asset is removed.
-                try {
-                    const rolledBack = supportedEntries[i].asset;
-                    const previousEntry = (initialLockfile.assets ?? []).find((a) => a.name === rolledBack.name && a.type === rolledBack.type && a.org === rolledBack.org);
-                    lockfile = previousEntry
-                        ? addAssetToLockfile(lockfile, previousEntry)
-                        : removeAssetFromLockfile(lockfile, rolledBack.name, rolledBack.type, rolledBack.org);
-                    await writeLockfile(options.projectDir, lockfile);
-                }
-                catch (error) {
-                    options.onProgress?.(`Warning: Failed to remove lockfile entry during rollback for ${result.name} — ${error instanceof Error ? error.message : String(error)}`);
+        // The failing asset isn't in `results`. Nothing else owns a path it created, so all of them go.
+        for (const path of created) {
+            try {
+                if (existsSync(path)) {
+                    await unlink(path);
                 }
             }
+            catch (error) {
+                options.onProgress?.(`Warning: Failed to delete file during rollback: ${path} — ${errorMessage(error)}`);
+            }
+        }
+        // Re-throw the original error with rollback context, keeping any API error code and
+        // recovery hint/command (e.g. from an API auth failure).
+        const failed = supportedEntries[results.length].asset;
+        const placed = results.map((result, i) => ({
+            asset: supportedEntries[i].asset,
+            entry: supportedEntries[i],
+            result,
+        }));
+        if (placed.some(({ entry }) => inPlace.has(entry) && inPlace.get(entry).version !== entry.version)) {
+            options.onProgress?.(`Keeping the install for ${options.adapter.tool}: it moved an installed asset to another version.`);
+            throw new InstallPlanError(failed, error, 0, true);
+        }
+        // Roll back the assets the plan added, in reverse order
+        const added = placed.filter(({ entry }) => !inPlace.has(entry));
+        if (added.length > 0) {
+            options.onProgress?.(`Install failed, rolling back ${added.length} installed asset(s)...`);
+            lockfile = await rollBackInstalledAssets(added, initialLockfile, lockfile, options);
             options.onProgress?.(`Rollback complete.`);
         }
-        // Re-throw the original error wrapped in InstallerError with rollback context,
-        // keeping any API error code and recovery hint/command (e.g. from an API auth failure).
-        const originalMessage = error instanceof Error ? error.message : String(error);
-        throw new InstallerError(`Install failed at asset "${supportedEntries[results.length]?.asset.name ?? 'unknown'}" ` +
-            `and ${results.length} previously installed asset(s) were rolled back: ${originalMessage}`, errorGuidance(error));
+        // The assets that were in place keep their files, of the same version, and get their entries back.
+        const kept = placed.filter(({ entry }) => inPlace.has(entry));
+        if (kept.length > 0) {
+            try {
+                for (const { asset } of kept) {
+                    const previous = findInstalledAsset(initialLockfile, asset.name, asset.type, asset.org);
+                    if (previous)
+                        lockfile = addAssetToLockfile(lockfile, previous);
+                }
+                await writeLockfile(options.projectDir, lockfile);
+            }
+            catch (error) {
+                options.onProgress?.(`Warning: Failed to restore lockfile entries during rollback — ${errorMessage(error)}`);
+            }
+        }
+        throw new InstallPlanError(failed, error, added.length);
     }
     return results;
 }
 /**
- * Append entry names to a string-array key in a config file (e.g., `enabledMcpjsonServers`
- * in `.claude/settings.local.json`), creating the file/array as needed and de-duplicating.
- * Used to auto-approve installed MCP servers so the tool doesn't prompt on open.
+ * Download the files of every plan entry this tool can place, without writing anything. A
+ * caller that replaces an installed asset downloads first, so a refused download leaves the
+ * installed version in place, then passes the result to {@link executeInstallPlan} as `files`.
  */
-async function addToEnabledList(enabledListFilePath, enabledListKey, names, onProgress) {
-    try {
-        const format = detectConfigFormat(enabledListFilePath);
-        let config = {};
-        if (existsSync(enabledListFilePath)) {
-            config = await readConfigFile(enabledListFilePath, format);
+export async function fetchPlanFiles(plan, adapter) {
+    const files = new Map();
+    for (const entry of plan.entries) {
+        if (!getPlacement(adapter, entry.asset.type))
+            continue;
+        try {
+            files.set(planEntryKey(entry), await fetchAssetFiles(entry.asset, entry.version, entry.asset.org));
         }
-        else {
-            const dir = dirname(enabledListFilePath);
-            if (!existsSync(dir)) {
-                await mkdir(dir, { recursive: true });
+        catch (error) {
+            throw new PlanDownloadError(entry.asset, error);
+        }
+    }
+    return files;
+}
+/**
+ * The message of an install failure for `asset`, for a caller whose own message already names
+ * it: a plan that failed at that asset gives just its cause; one that failed at another asset
+ * keeps the installer's message, which names that asset.
+ */
+export function installFailureMessage(error, asset) {
+    const atAsset = error instanceof InstallPlanError &&
+        error.asset.name === asset.name &&
+        error.asset.type === asset.type &&
+        error.asset.org === asset.org;
+    return errorMessage(atAsset ? error.cause : error);
+}
+/** The entries of `plan` the adapter's tool has a placement for, in plan order. */
+export function placeableEntries(plan, adapter) {
+    return plan.entries.filter((entry) => getPlacement(adapter, entry.asset.type));
+}
+/**
+ * Undo the installs of `installed` for the adapter's tool, in reverse order (best-effort): delete
+ * their placed files, revert their config entries (deleting a config file they created once it is
+ * empty), put back the memory-template block they replaced or take out the one they added (deleting
+ * a file they created once it is empty), take the names they added out of an enabled list, and give
+ * each asset its lockfile entry from `before`, or remove it. A file or config entry an asset of
+ * `before` also owns is kept.
+ * Returns `lockfile` with the entries reverted, as written.
+ */
+export async function rollBackInstalledAssets(installed, before, lockfile, options) {
+    for (const { asset: rolledBack, result } of installed.toReversed()) {
+        options.onProgress?.(`Rolling back ${result.name}...`);
+        // Delete placed files (best-effort), except one another asset installed before this plan
+        // also owns: a global and an org asset of one name and type can share a placement.
+        const ownedByOthers = pathsOwnedByOthers(before, rolledBack, options.adapter, options.projectDir);
+        for (const file of result.filesPlaced) {
+            if (ownedByOthers.has(file.destination))
+                continue;
+            try {
+                if (existsSync(file.destination)) {
+                    await unlink(file.destination);
+                }
+            }
+            catch (error) {
+                options.onProgress?.(`Warning: Failed to delete file during rollback: ${file.destination} — ${errorMessage(error)}`);
             }
         }
-        const existing = Array.isArray(config[enabledListKey]) ? config[enabledListKey] : [];
-        const list = existing.filter((v) => typeof v === 'string');
-        let changed = !Array.isArray(config[enabledListKey]);
-        for (const name of names) {
-            if (!list.includes(name)) {
-                list.push(name);
-                changed = true;
+        // Revert config file entries (best-effort), except one holding the value of an asset from
+        // before this plan that also owns it
+        const placement = getPlacement(options.adapter, result.type);
+        const entriesOwnedByOthers = configEntriesOwnedByOthers(before, rolledBack, options.adapter, options.projectDir);
+        const kept = new Set();
+        for (const entry of result.configEntriesCreated) {
+            try {
+                if (await holdsAnotherOwnersValue(entry, entriesOwnedByOthers, options.projectDir)) {
+                    kept.add(entry.key);
+                    continue;
+                }
+                const configPath = join(options.projectDir, entry.file);
+                const format = resolveConfigFormat(configPath, placement);
+                const created = result.configFilesCreated?.includes(entry.file) ?? false;
+                await revertConfigEntry(configPath, entry.key, entry.command, format, created, options.onProgress);
+            }
+            catch (error) {
+                options.onProgress?.(`Warning: Failed to revert config entry ${entry.key} during rollback — ${errorMessage(error)}`);
             }
         }
-        if (changed) {
-            config[enabledListKey] = list;
-            await writeConfigFile(enabledListFilePath, config, format, onProgress);
+        // Give a memory-template's file back the block of that name it had before, or none
+        if (result.blockWritten) {
+            await revertMemoryBlock(options.projectDir, result.name, result.blockWritten, options.onProgress);
+        }
+        // Take the names the install added out of the enabled list again, except one whose entry was
+        // kept for its other owner (as uninstall does)
+        const { configKey, enabledListFile, enabledListKey } = placement ?? {};
+        const names = (result.enabledListAdded ?? []).filter((name) => !kept.has(`${configKey}.${name}`));
+        if (enabledListFile && enabledListKey && names.length > 0) {
+            await removeFromEnabledList(join(options.projectDir, enabledListFile), enabledListKey, names, result.configFilesCreated?.includes(enabledListFile) ?? false, options.onProgress);
+        }
+        // Revert the lockfile entry using the in-memory lockfile (best-effort). An asset that
+        // was already recorded before this plan ran (a sync/update reinstall, or a second
+        // tool's pass in a multi-tool install) gets its previous entry back, so other tools'
+        // config entries survive; a newly added asset is removed.
+        try {
+            const previousEntry = (before.assets ?? []).find((a) => a.name === rolledBack.name && a.type === rolledBack.type && a.org === rolledBack.org);
+            lockfile = previousEntry
+                ? addAssetToLockfile(lockfile, previousEntry)
+                : removeAssetFromLockfile(lockfile, rolledBack.name, rolledBack.type, rolledBack.org);
+            await writeLockfile(options.projectDir, lockfile);
+        }
+        catch (error) {
+            options.onProgress?.(`Warning: Failed to remove lockfile entry during rollback for ${result.name} — ${errorMessage(error)}`);
         }
     }
-    catch (error) {
-        // Non-fatal — log but don't fail the install
-        onProgress?.(`Warning: Failed to update enabled list ${enabledListFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+    return lockfile;
+}
+/** Record `owner` as one of the assets that placed the file at `key`, or wrote the shared entry. */
+function addOwner(owned, key, owner) {
+    const owners = owned.get(key);
+    if (owners) {
+        owners.push(owner);
     }
+    else {
+        owned.set(key, [owner]);
+    }
+}
+/** The regular expression source of the `<!-- ATK: {name} -->` block, delimiters included. */
+function atkBlockPattern(assetName) {
+    const escapedName = assetName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return `<!-- ATK: ${escapedName} -->\\n[\\s\\S]*?<!-- /ATK: ${escapedName} -->`;
+}
+/**
+ * Map each name of a keyed config entry other tools have to the owners of each such entry: the
+ * assets that recorded it for one other tool, in one file. Assets the adapter's tool can't hold
+ * are left out, as in {@link buildManagedEntries}.
+ */
+function buildEntryOwnersElsewhere(lockfile, adapter) {
+    const byName = new Map();
+    for (const asset of lockfile.assets ?? []) {
+        if (isExcludedForTool(asset, adapter.tool) || !getPlacement(adapter, asset.type))
+            continue;
+        for (const entry of getOtherToolsConfigEntries(asset, adapter)) {
+            const name = configEntryName(entry.key);
+            if (entry.command !== undefined || name === undefined)
+                continue;
+            const byFile = byName.get(name) ?? new Map();
+            byName.set(name, byFile);
+            addOwner(byFile, sharedEntryKey({ file: normalizeConfigPath(entry.file), key: entry.key }), asset);
+        }
+    }
+    return new Map([...byName].map(([name, byFile]) => [name, [...byFile.values()]]));
 }
 /**
- * Build a set of all file paths managed by ATK from the given lockfile.
- * Used for conflict detection — files in this set can be safely overwritten.
+ * Map each memory-template block and keyed config entry the given lockfile's assets wrote for the
+ * adapter's tool to those assets. Used for conflict detection, like {@link buildManagedPaths}.
+ */
+function buildManagedEntries(lockfile, projectDir, adapter) {
+    const entries = new Map();
+    for (const asset of lockfile.assets ?? []) {
+        if (isExcludedForTool(asset, adapter.tool))
+            continue;
+        const placement = getPlacement(adapter, asset.type);
+        if (!placement)
+            continue;
+        if (asset.type === 'memory-template') {
+            addOwner(entries, sharedEntryKey(memoryTemplateBlock(placement, asset.name, projectDir)), asset);
+        }
+        for (const entry of getConfigEntriesForTool(asset, adapter)) {
+            // A hook's event entry is an array every hook shares; its own group is found by its command.
+            if (entry.command !== undefined)
+                continue;
+            addOwner(entries, sharedEntryKey({ file: join(projectDir, entry.file), key: entry.key }), asset);
+        }
+    }
+    return entries;
+}
+/**
+ * Map every file path managed by ATK in the given lockfile to the assets that installed it.
+ * Used for conflict detection — an asset may overwrite only the files it installed itself.
  * Resolves installed paths dynamically via the adapter rather than reading them from the lockfile.
  */
-function buildManagedPathsSet(lockfile, projectDir, adapter) {
-    const paths = new Set();
+function buildManagedPaths(lockfile, projectDir, adapter) {
+    const paths = new Map();
     for (const asset of lockfile.assets ?? []) {
         const resolved = resolveInstalledPaths(asset, adapter, projectDir);
         for (const file of resolved.files) {
-            paths.add(join(projectDir, file.installedPath));
+            addOwner(paths, join(projectDir, file.installedPath), asset);
         }
     }
     return paths;
 }
 /**
- * Check if a file at the destination path would conflict with an existing non-ATK file.
- * Throws InstallerError if the file exists and is not tracked in the lockfile.
- * ATK-managed files (in the lockfile) can be safely overwritten (e.g., reinstall/update).
+ * Throw a FileConflictError if another installed asset wrote `entry` and `asset` didn't. An entry
+ * no installed asset wrote is left to the merge, as before. An asset that recorded the entry of
+ * that name for another tool together with all of its owners here (a forced install, or one from
+ * before installs refused a shared entry) shares it here too: otherwise the first of them to sync
+ * a newly added tool would lock the others out of it.
+ */
+function checkEntryConflict(entry, managedEntries, ownersElsewhere, asset) {
+    const owners = managedEntries.get(sharedEntryKey(entry));
+    if (!owners || isOwner(owners, asset)) {
+        return;
+    }
+    const sharedElsewhere = (entry.entry ? ownersElsewhere.get(entry.entry.name) : undefined)?.some((coOwners) => isOwner(coOwners, asset) && owners.every((owner) => isOwner(coOwners, owner)));
+    if (sharedElsewhere) {
+        return;
+    }
+    throw new FileConflictError(entry.file, owners[0], entry.label);
+}
+/**
+ * Check if a file at the destination path would conflict with a file `asset` didn't install.
+ * Throws FileConflictError if the file exists and is not tracked in the lockfile, or is tracked
+ * only for other assets (a global and an org asset of one name and type share a placement).
+ * The asset's own files can be safely overwritten (e.g., reinstall/update).
  */
-async function checkFileConflict(destPath, managedPaths) {
+async function checkFileConflict(destPath, managedPaths, asset) {
     if (!existsSync(destPath)) {
         return;
     }
-    if (managedPaths.has(destPath)) {
+    const owners = managedPaths.get(destPath) ?? [];
+    if (isOwner(owners, asset)) {
+        return;
+    }
+    throw new FileConflictError(destPath, owners[0]);
+}
+/**
+ * Throw a FileConflictError if the config entry `entry` names already exists without ATK's
+ * `_managedBy` marker and no installed asset wrote it: the user wrote it, so only --force replaces
+ * it, as with a file. A config file that doesn't parse is left to the merge, which warns.
+ */
+async function checkUserEntryConflict(entry, managedEntries, format) {
+    if (!entry.entry || managedEntries.has(sharedEntryKey(entry)) || !existsSync(entry.file)) {
+        return;
+    }
+    const config = await readConfigFile(entry.file, format).catch(() => undefined);
+    const section = config?.[entry.entry.section];
+    const existing = isRecord(section) ? section[entry.entry.name] : undefined;
+    if (existing === undefined || (isRecord(existing) && existing['_managedBy'] === 'atk')) {
         return;
     }
-    throw new InstallerError(`File conflict: "${destPath}" already exists and was not installed by ATK. Use --force to overwrite.`);
+    throw new FileConflictError(entry.file, undefined, entry.label);
+}
+/** The name a keyed config entry has in its section: `neon` for `mcpServers.neon`. */
+function configEntryName(key) {
+    const dotIndex = key.indexOf('.');
+    return dotIndex === -1 ? undefined : key.slice(dotIndex + 1);
 }
 /**
  * Fetch all files for an asset version from the ATK API, plus its
@@ -225,7 +468,7 @@ async function fetchAssetFiles(asset, version, org) {
         if (error instanceof InstallerError) {
             throw error;
         }
-        const message = error instanceof Error ? error.message : String(error);
+        const message = errorMessage(error);
         throw new InstallerError(message, errorGuidance(error));
     }
 }
@@ -244,11 +487,36 @@ async function fetchManifestEntrypoint(ref, version) {
         return undefined;
     }
 }
+/** The `<!-- ATK: {name} -->` block in `content`, delimiters included, if it has one. */
+function findAtkBlock(content, assetName) {
+    return new RegExp(atkBlockPattern(assetName)).exec(content)?.[0];
+}
+/**
+ * The named entries of a config fragment: the map at `content[configKey]`, then `content[fragmentKey]`
+ * (for tools whose target key differs from the asset content's key, e.g. `mcp_servers` vs
+ * `mcpServers`), and finally the whole content. Entries that aren't objects are skipped.
+ */
+function fragmentEntries(content, configKey, fragmentKey) {
+    const pickMap = (key) => {
+        if (!key)
+            return undefined;
+        const candidate = content[key];
+        return candidate && typeof candidate === 'object' && !Array.isArray(candidate)
+            ? candidate
+            : undefined;
+    };
+    const inner = pickMap(configKey) ?? pickMap(fragmentKey) ?? content;
+    return Object.entries(inner).filter((pair) => !!pair[1] && typeof pair[1] === 'object');
+}
 /**
  * Install a single asset from the install plan.
- * Accepts the current in-memory lockfile and returns the updated lockfile alongside the result.
+ * Accepts the current in-memory lockfile and returns the updated lockfile alongside the result,
+ * and the shared entries the asset wrote.
+ * While it places the asset's files, `created` holds each path it writes where no file was (added
+ * before the write), so a caller can remove them when placing fails partway. It is emptied once
+ * every file is placed.
  */
-async function installAsset(entry, options, managedPaths, lockfile) {
+async function installAsset(entry, options, managedPaths, managedEntries, ownersElsewhere, lockfile, created) {
     const { asset } = entry;
     const { adapter, force, onProgress, pin, projectDir } = options;
     onProgress?.(`Installing ${asset.name}...`);
@@ -259,21 +527,56 @@ async function installAsset(entry, options, managedPaths, lockfile) {
     }
     // Determine base path
     const basePath = projectDir;
-    // Fetch asset files from the ATK API (version-aware, org-aware)
-    const { entrypoint: declaredEntrypoint, files: assetFiles } = await fetchAssetFiles(asset, entry.version, entry.asset.org);
+    // Fetch asset files from the ATK API (version-aware, org-aware), unless the caller already did.
+    // A caller that downloaded first may have removed the installed files since, so a gap in its
+    // download must not turn into a fresh request that can be refused.
+    const prefetched = options.files?.get(planEntryKey(entry));
+    if (options.files && !prefetched) {
+        throw new InstallerError(`The files of "${asset.name}"@${entry.version} were not downloaded before the install.`);
+    }
+    const { entrypoint: declaredEntrypoint, files: assetFiles } = prefetched ?? (await fetchAssetFiles(asset, entry.version, entry.asset.org));
     // Find the entrypoint file
     const entrypointFile = assetFiles.find((f) => isEntrypoint(f.relativePath, asset.type, declaredEntrypoint));
+    // Determine merge content for configMerge mode (a keyed merge; a hook merge doesn't use it)
+    let mergeContent;
+    if (placement.configMerge && !placement.configHookMerge && entrypointFile) {
+        try {
+            mergeContent = JSON.parse(entrypointFile.content.toString('utf-8'));
+        }
+        catch {
+            // If content isn't valid JSON, fall back to marker-only behavior
+        }
+    }
+    // The target config file's serialization format (JSON by default; TOML for tools like Codex
+    // CLI), resolved once here and threaded into the entry checks and every merge helper.
+    const configFormat = placement.configFile
+        ? resolveConfigFormat(join(basePath, placement.configFile), placement)
+        : 'json';
+    // Check the block or config entries the asset writes into shared files before writing anything,
+    // so a conflict leaves another asset's entry, or one the user wrote, as it was.
+    const sharedEntries = plannedSharedEntries(asset.name, asset.type, placement, basePath, mergeContent);
+    if (!force) {
+        for (const shared of sharedEntries) {
+            checkEntryConflict(shared, managedEntries, ownersElsewhere, asset);
+            await checkUserEntryConflict(shared, managedEntries, configFormat);
+        }
+    }
     // Branch on placement type
     const placedFiles = [];
     const filesPlaced = [];
     const configEntries = [];
+    // The shared entries written so far: the merge helpers warn and write nothing when they fail.
+    const written = [];
+    // The memory-template block written, which a rollback undoes.
+    let blockWritten;
     if (placement.fileless) {
         // Fileless placement (e.g., MCP configs) — no files placed on disk
         // Config merging handled below
     }
     else if (asset.type === 'memory-template') {
         // Memory templates append to a shared file with delimiters
-        const targetPath = join(basePath, placement.path.replace(/\{name\}/g, asset.name));
+        const block = memoryTemplateBlock(placement, asset.name, basePath);
+        const targetPath = block.file;
         const targetDir = dirname(targetPath);
         if (!existsSync(targetDir)) {
             await mkdir(targetDir, { recursive: true });
@@ -284,29 +587,36 @@ async function installAsset(entry, options, managedPaths, lockfile) {
         }
         const content = (entrypointFile?.content ?? firstFile.content).toString('utf-8');
         const delimitedContent = `<!-- ATK: ${asset.name} -->\n${content}\n<!-- /ATK: ${asset.name} -->`;
-        if (existsSync(targetPath)) {
-            const existing = await readFile(targetPath, 'utf-8');
-            // Strip any existing ATK block for this asset before appending the new one
-            const cleaned = stripAtkBlock(existing, asset.name);
-            await writeTextFile(targetPath, cleaned.trimEnd() + '\n\n' + delimitedContent + '\n');
-        }
-        else {
-            await writeTextFile(targetPath, delimitedContent + '\n');
-        }
+        const existing = existsSync(targetPath) ? await readFile(targetPath, 'utf-8') : undefined;
+        // Strip any existing ATK block for this asset before appending the new one
+        const rest = existing === undefined ? '' : stripAtkBlock(existing, asset.name).trimEnd();
+        await writeTextFile(targetPath, (rest ? `${rest}\n\n` : '') + delimitedContent + '\n');
+        written.push(block);
+        const replaced = existing === undefined ? undefined : findAtkBlock(existing, asset.name);
+        blockWritten = {
+            created: existing === undefined,
+            file: toRelativePosix(projectDir, targetPath),
+            ...(replaced !== undefined ? { replaced } : {}),
+        };
         // Memory-template entries are tracked as placed files, not config entries.
         // They don't go through updateConfigFile() and have no config entry checksum.
     }
     else if (placement.entrypointName) {
         // Directory-based placement (e.g., skills)
-        for (const file of assetFiles) {
-            const destPath = resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, placement.entrypointName, declaredEntrypoint);
+        const destinations = assetFiles.map((file) => resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, placement.entrypointName, declaredEntrypoint));
+        // Check every destination before writing any, so a conflict leaves none of the asset's files behind.
+        if (!force) {
+            for (const destPath of destinations)
+                await checkFileConflict(destPath, managedPaths, asset);
+        }
+        for (const [index, file] of assetFiles.entries()) {
+            const destPath = destinations[index];
             const destDir = dirname(destPath);
-            if (!force) {
-                await checkFileConflict(destPath, managedPaths);
-            }
             if (!existsSync(destDir)) {
                 await mkdir(destDir, { recursive: true });
             }
+            if (!existsSync(destPath))
+                created.push(destPath);
             await writeBinaryFile(destPath, file.content);
             const checksum = hashBytes(file.content);
             placedFiles.push({
@@ -322,15 +632,19 @@ async function installAsset(entry, options, managedPaths, lockfile) {
     }
     else {
         // Default single-file placement
-        for (const file of assetFiles) {
-            const destPath = resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, undefined, declaredEntrypoint);
+        const destinations = assetFiles.map((file) => resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, undefined, declaredEntrypoint));
+        if (!force) {
+            for (const destPath of destinations)
+                await checkFileConflict(destPath, managedPaths, asset);
+        }
+        for (const [index, file] of assetFiles.entries()) {
+            const destPath = destinations[index];
             const destDir = dirname(destPath);
-            if (!force) {
-                await checkFileConflict(destPath, managedPaths);
-            }
             if (!existsSync(destDir)) {
                 await mkdir(destDir, { recursive: true });
             }
+            if (!existsSync(destPath))
+                created.push(destPath);
             await writeBinaryFile(destPath, file.content);
             const checksum = hashBytes(file.content);
             placedFiles.push({
@@ -350,12 +664,17 @@ async function installAsset(entry, options, managedPaths, lockfile) {
             await makeExecutable(scriptDest);
         }
     }
-    // Handle config file updates if needed. The target file's serialization format
-    // (JSON by default; TOML for tools like Codex CLI) is resolved once here and
-    // threaded into every merge helper.
-    const configFormat = placement.configFile
-        ? resolveConfigFormat(join(basePath, placement.configFile), placement)
-        : 'json';
+    // Every file is placed, and the config entries below can point at them (a hook runs its script),
+    // so a failure from here on leaves them in place.
+    created.length = 0;
+    // The config files the writes below can create, which a rollback then removes once empty.
+    const absentConfigFiles = [placement.configFile, placement.enabledListFile]
+        .filter((file) => !!file)
+        .map((file) => join(basePath, file))
+        .filter((path) => !existsSync(path));
+    // The names the install adds to the placement's enabled list, which a rollback takes out again.
+    let enabledListAdded = [];
+    // Handle config file updates if needed.
     if (placement.configFile && placement.configKey && placement.configHookMerge) {
         // Hook placement: merge the asset's hookConfig event bindings into the tool
         // config file as valid event arrays (e.g. settings.json hooks.Stop[]), with the
@@ -365,16 +684,6 @@ async function installAsset(entry, options, managedPaths, lockfile) {
         configEntries.push(...hookEntries);
     }
     else if (placement.configFile && placement.configKey) {
-        // Determine merge content for configMerge mode
-        let mergeContent;
-        if (placement.configMerge && entrypointFile) {
-            try {
-                mergeContent = JSON.parse(entrypointFile.content.toString('utf-8'));
-            }
-            catch {
-                // If content isn't valid JSON, fall back to marker-only behavior
-            }
-        }
         if (placement.configFragment) {
             // Fragment merge (e.g., mcp-config): the asset content is a full config fragment
             // (e.g. a whole .mcp.json). Merge the entries inside content[configKey] into
@@ -385,7 +694,7 @@ async function installAsset(entry, options, managedPaths, lockfile) {
             // Auto-register the merged entry names into an enabled-list (e.g. enabledMcpjsonServers
             // in settings.local.json) so the tool auto-approves them.
             if (names.length > 0 && placement.enabledListFile && placement.enabledListKey) {
-                await addToEnabledList(join(basePath, placement.enabledListFile), placement.enabledListKey, names, onProgress);
+                enabledListAdded = await addToEnabledList(join(basePath, placement.enabledListFile), placement.enabledListKey, names, onProgress);
             }
         }
         else {
@@ -395,6 +704,10 @@ async function installAsset(entry, options, managedPaths, lockfile) {
             }
         }
     }
+    written.push(...sharedEntries.filter((shared) => configEntries.some((c) => !c.command && c.key === shared.key)));
+    const configFilesCreated = absentConfigFiles
+        .filter((path) => existsSync(path))
+        .map((path) => toRelativePosix(projectDir, path));
     // Config entries are tool-specific but the lockfile is shared across tools: tag this
     // tool's entries and carry over whatever other tools already registered for this asset,
     // so a multi-tool install/sync/update never drops another tool's registration record.
@@ -431,14 +744,33 @@ async function installAsset(entry, options, managedPaths, lockfile) {
     return {
         lockfile: updatedLockfile,
         result: {
+            ...(blockWritten ? { blockWritten } : {}),
             ...(options.bundleOrigin ? { bundleOrigin: options.bundleOrigin } : {}),
             configEntriesCreated: configEntries,
+            ...(configFilesCreated.length > 0 ? { configFilesCreated } : {}),
+            ...(enabledListAdded.length > 0 ? { enabledListAdded } : {}),
             filesPlaced,
             installReason: entry.reason,
             name: asset.name,
             type: asset.type,
             version: entry.version,
         },
+        sharedEntries: written,
+    };
+}
+/** Whether `asset` is one of `owners`. */
+function isOwner(owners, asset) {
+    return owners.some((o) => o.name === asset.name && o.type === asset.type && o.org === asset.org);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The `<!-- ATK: {name} -->` block a memory-template asset writes into its placement's file. */
+function memoryTemplateBlock(placement, name, basePath) {
+    return {
+        file: join(basePath, placement.path.replace(/\{name\}/g, name)),
+        key: `ATK:${name}`,
+        label: `"${name}" block`,
     };
 }
 /**
@@ -450,9 +782,7 @@ async function installAsset(entry, options, managedPaths, lockfile) {
  * with the `_managedBy: 'atk'` marker. Returns one config entry per merged name (for lockfile
  * tracking / checksum verification) plus the list of names that were merged.
  *
- * The inner map is looked up at `content[configKey]`, then `content[fragmentKey]` (for tools
- * whose target key differs from the asset content's key, e.g. `mcp_servers` vs `mcpServers`),
- * and finally the whole content is treated as the inner map.
+ * The entries are found by {@link fragmentEntries}.
  */
 async function mergeFragmentConfig(configFilePath, configKey, format, projectDir, mergeContent, fragmentKey, onProgress) {
     const empty = { entries: [], names: [] };
@@ -460,17 +790,8 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
         return empty;
     }
     try {
-        const pickMap = (key) => {
-            if (!key)
-                return undefined;
-            const candidate = mergeContent[key];
-            return candidate && typeof candidate === 'object' && !Array.isArray(candidate)
-                ? candidate
-                : undefined;
-        };
-        const inner = pickMap(configKey) ?? pickMap(fragmentKey) ?? mergeContent;
-        const innerNames = Object.keys(inner).filter((name) => inner[name] && typeof inner[name] === 'object');
-        if (innerNames.length === 0) {
+        const inner = fragmentEntries(mergeContent, configKey, fragmentKey);
+        if (inner.length === 0) {
             return empty;
         }
         let config = {};
@@ -488,8 +809,8 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
         }
         const section = config[configKey];
         const entries = [];
-        for (const name of innerNames) {
-            const value = normalizeForFormat({ ...inner[name], _managedBy: 'atk' }, format);
+        for (const [name, fragment] of inner) {
+            const value = normalizeForFormat({ ...fragment, _managedBy: 'atk' }, format);
             section[name] = value;
             entries.push({
                 checksum: computeConfigEntryChecksum(value),
@@ -498,11 +819,11 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
             });
         }
         await writeConfigFile(configFilePath, config, format, onProgress);
-        return { entries, names: innerNames };
+        return { entries, names: inner.map(([name]) => name) };
     }
     catch (error) {
         // Non-fatal — log but don't fail the install
-        onProgress?.(`Warning: Failed to merge config fragment into ${configFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to merge config fragment into ${configFilePath} — ${errorMessage(error)}`);
         return empty;
     }
 }
@@ -557,10 +878,40 @@ async function mergeHookConfig(configFilePath, configKey, format, hookConfig, co
     }
     catch (error) {
         // Non-fatal — log but don't fail the install
-        onProgress?.(`Warning: Failed to merge hook config into ${configFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to merge hook config into ${configFilePath} — ${errorMessage(error)}`);
         return [];
     }
 }
+/** The {@link PlanFiles} key of a plan entry: one asset version. */
+function planEntryKey(entry) {
+    return `${entry.asset.type}:${entry.asset.org ?? ''}:${entry.asset.name}@${entry.version}`;
+}
+/**
+ * The memory-template block or keyed config entries an asset of `name` and `type` will write: the
+ * fragment's own entry names for a fragment merge, the asset name for any other keyed merge. A
+ * hook's event entries are shared by every hook, so they aren't among them.
+ */
+function plannedSharedEntries(name, type, placement, basePath, mergeContent) {
+    // The same routing as installAsset: a file-placing memory-template writes its block, then any
+    // keyed (not hook) config merge writes its entries.
+    const entries = !placement.fileless && type === 'memory-template' ? [memoryTemplateBlock(placement, name, basePath)] : [];
+    const { configFile, configKey } = placement;
+    if (!configFile || !configKey || placement.configHookMerge) {
+        return entries;
+    }
+    const names = placement.configFragment
+        ? fragmentEntries(mergeContent ?? {}, configKey, placement.configFragmentKey).map(([entryName]) => entryName)
+        : [name];
+    return [
+        ...entries,
+        ...names.map((entryName) => ({
+            entry: { name: entryName, section: configKey },
+            file: join(basePath, configFile),
+            key: `${configKey}.${entryName}`,
+            label: `"${configKey}.${entryName}" entry`,
+        })),
+    ];
+}
 /**
  * Resolve the destination file path for an asset file.
  * For directory-based placement (entrypointName set), the path is a directory template.
@@ -587,9 +938,10 @@ function resolveFilePath(pathTemplate, assetName, basePath, relativePath, assetT
 /**
  * Revert a config file entry created during installation.
  * Reads the config file, removes the entry at the given key path (e.g., "mcpServers.my-mcp"),
- * and writes it back. If the parent section becomes empty, it is also removed.
+ * and writes it back. If the parent section becomes empty, it is also removed. A file the
+ * install created (`deleteWhenEmpty`) is deleted instead once nothing is left in it.
  */
-async function revertConfigEntry(configFilePath, keyPath, command, format, onProgress) {
+async function revertConfigEntry(configFilePath, keyPath, command, format, deleteWhenEmpty, onProgress) {
     if (!existsSync(configFilePath)) {
         return;
     }
@@ -619,12 +971,45 @@ async function revertConfigEntry(configFilePath, keyPath, command, format, onPro
                 delete config[sectionKey];
             }
         }
+        if (deleteWhenEmpty && Object.keys(config).length === 0) {
+            await unlink(configFilePath);
+            return;
+        }
         await writeConfigFile(configFilePath, config, format, onProgress);
     }
     catch (error) {
-        onProgress?.(`Warning: Failed to revert config entry ${keyPath} in ${configFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to revert config entry ${keyPath} in ${configFilePath} — ${errorMessage(error)}`);
     }
 }
+/**
+ * Undo the write of a memory-template block (best-effort): put back the block of that name the
+ * install replaced, or take the block out, deleting the file once it is empty if the install
+ * created it.
+ */
+async function revertMemoryBlock(projectDir, assetName, { created, file, replaced }, onProgress) {
+    const path = join(projectDir, file);
+    try {
+        if (!existsSync(path))
+            return;
+        const content = await readFile(path, 'utf-8');
+        const reverted = (replaced === undefined
+            ? stripAtkBlock(content, assetName)
+            : content.replace(new RegExp(atkBlockPattern(assetName)), () => replaced)).trimEnd();
+        if (created && reverted.trim() === '') {
+            await unlink(path);
+        }
+        else {
+            await writeTextFile(path, `${reverted}\n`);
+        }
+    }
+    catch (error) {
+        onProgress?.(`Warning: Failed to revert the "${assetName}" block during rollback — ${errorMessage(error)}`);
+    }
+}
+/** The {@link ManagedEntries} key of a shared entry. */
+function sharedEntryKey(entry) {
+    return `${entry.file}#${entry.key}`;
+}
 /**
  * Remove an existing ATK-delimited block for the given asset name from file content.
  * Matches blocks of the form:
@@ -634,9 +1019,7 @@ async function revertConfigEntry(configFilePath, keyPath, command, format, onPro
  * along with surrounding blank lines to keep formatting clean.
  */
 function stripAtkBlock(content, assetName) {
-    const escapedName = assetName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const pattern = new RegExp(`(\n{0,2})<!-- ATK: ${escapedName} -->\\n[\\s\\S]*?<!-- /ATK: ${escapedName} -->\\n?`, 'g');
-    return content.replace(pattern, '');
+    return content.replace(new RegExp(`(\n{0,2})${atkBlockPattern(assetName)}\\n?`, 'g'), '');
 }
 /**
  * Update a tool config file (e.g., settings.json) with an entry for the installed asset.
@@ -680,7 +1063,7 @@ async function updateConfigFile(configFilePath, configKey, format, assetName, as
     }
     catch (error) {
         // Non-fatal — log but don't fail the install
-        onProgress?.(`Warning: Failed to update config file ${configFilePath} — ${error instanceof Error ? error.message : String(error)}`);
+        onProgress?.(`Warning: Failed to update config file ${configFilePath} — ${errorMessage(error)}`);
         return null;
     }
 }