@detergent-software/atk 8.6.2-dev.1 → 8.7.0-dev.10

package/build/lib/installer.js

@@ -1,15 +1,16 @@
 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 { adapterAsPlaced, configDirMove, getPlacement, isEntrypoint, recordUserConfigDir, resolveInstalledPaths, } from './adapter.js';
 import { carryExclusions, declarationAllows, declaresTool, isExcludedForTool } from './asset-tools.js';
-import { computeConfigEntryChecksum, computeHookGroupChecksum, hashBytes } from './checksum.js';
+import { computeConfigEntryChecksum, computeHookGroupChecksum, hashBytes, verifyChecksum } from './checksum.js';
 import { getConfigEntriesForTool, getOtherToolsConfigEntries, mergeConfigEntriesForTool, normalizeConfigPath, } from './config-entries.js';
-import { normalizeForFormat, readConfigFile, resolveConfigFormat, writeConfigFile, } from './config-file.js';
+import { normalizeForFormat, readConfigFile, removeEmptiedConfigFile, resolveConfigFormat, writeConfigFile, } from './config-file.js';
+import { configLockPath, withConfigLock } from './config-lock.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 { buildHookGroup, hookCommand, hookGroupOwnsCommand, removeHookGroup } from './hook-config.js';
 import { hookScriptPath, makeExecutable } from './hook-script.js';
 import { isInstalledForTool } from './installed-for-tool.js';
 import { addAssetToLockfile, findInstalledAsset, readLockfile, removeAssetFromLockfile, writeLockfile, } from './lockfile.js';
@@ -17,10 +18,18 @@ 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 { fromRoot } from './root-path.js';
+import { scopedCommand } from './scope.js';
+import { removePlacedFiles } from './uninstaller.js';
 import { writeBinaryFile, writeTextFile } from './write-file.js';
 export class InstallerError extends ApiCodeError {
     name = 'InstallerError';
 }
+/** The guidance for an asset type no tool of the user scope has a user-level placement for. */
+const NO_USER_PLACEMENT = {
+    command: 'atk setup --user',
+    hint: 'Install it in a project (without --user), or add a tool to the user scope that has one.',
+};
 /**
  * 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
@@ -73,19 +82,22 @@ export class PlanDownloadError extends InstallPlanError {
  * 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
  * tool skipped every entry, nothing was installed — surface that as an error rather
- * than reporting a successful no-op.
+ * than reporting a successful no-op. The refusal's setup command is `scope`'s.
  */
-export function assertInstalledByAnyTool(plan, toolResults) {
+export function assertInstalledByAnyTool(plan, toolResults, scope = 'project') {
     if (plan.entries.length === 0 || toolResults.some((r) => r.results.length > 0)) {
         return;
     }
-    const undeclared = undeclaredHookError(plan, toolResults.map((r) => r.tool));
+    const undeclared = undeclaredHookError(plan, toolResults.map((r) => r.tool), scope);
     if (undeclared)
         throw undeclared;
     const types = [...new Set(plan.entries.map((e) => e.asset.type))].join(', ');
     const tools = toolResults.map((r) => r.tool).join(', ');
+    if (scope === 'user') {
+        throw new InstallerError(`None of the user scope's tools (${tools}) has a user-level ${types}.`, NO_USER_PLACEMENT);
+    }
     throw new InstallerError(`None of the configured tools (${tools}) support asset type "${types}"`, {
-        command: 'atk setup',
+        command: scopedCommand('atk setup', scope),
         hint: 'Add a tool that supports this asset type, or install it in a project configured for one.',
     });
 }
@@ -101,18 +113,21 @@ export function assertInstalledByAnyTool(plan, toolResults) {
  */
 export async function executeInstallPlan(plan, options) {
     const results = [];
-    // Ensure .gitignore has entries for ATK-managed asset directories (non-fatal)
-    try {
-        await ensureGitignoreEntries(options.projectDir, options.adapter);
-    }
-    catch {
-        options.onProgress?.('Warning: Failed to update .gitignore — continuing with install');
+    // Ensure .gitignore has entries for ATK-managed asset directories (non-fatal). The user root
+    // isn't a project, and its .gitignore is often git's global excludes file, so it's left alone.
+    if (options.scope !== 'user') {
+        try {
+            await ensureGitignoreEntries(options.projectDir, options.adapter);
+        }
+        catch {
+            options.onProgress?.('Warning: Failed to update .gitignore — continuing with install');
+        }
     }
     // Read lockfile once — used for both conflict detection and per-asset install logic
     let lockfile = await readLockfile(options.projectDir);
     const initialLockfile = lockfile;
     // 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);
+    const managedPaths = await 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
@@ -125,7 +140,9 @@ export async function executeInstallPlan(plan, options) {
     const supportedEntries = placeableEntries(plan, options.adapter);
     for (const entry of plan.entries) {
         if (!getPlacement(options.adapter, entry.asset.type)) {
-            options.onProgress?.(`Skipping ${entry.asset.name}: ${options.adapter.displayName} does not support ${entry.asset.type} assets`);
+            options.onProgress?.(options.scope === 'user'
+                ? `Skipping ${entry.asset.name}: ${options.adapter.displayName} has no user-level ${entry.asset.type}`
+                : `Skipping ${entry.asset.name}: ${options.adapter.displayName} does not support ${entry.asset.type} assets`);
         }
         else if (!declarationAllows(entry.asset.type, entry.versionData.tools, options.adapter.tool)) {
             const tools = entry.versionData.tools.join(', ');
@@ -133,9 +150,12 @@ export async function executeInstallPlan(plan, options) {
         }
     }
     if (supportedEntries.length === 0 && plan.entries.length > 0 && !options.skipUnsupported) {
-        const undeclared = undeclaredHookError(plan, [options.adapter.tool]);
+        const undeclared = undeclaredHookError(plan, [options.adapter.tool], options.scope);
         if (undeclared)
             throw undeclared;
+        if (options.scope === 'user') {
+            throw new InstallerError(`${options.adapter.displayName} has no user-level ${plan.entries[0].asset.type}.`, NO_USER_PLACEMENT);
+        }
         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.
@@ -148,11 +168,16 @@ export async function executeInstallPlan(plan, options) {
     }
     // The files the asset being placed wrote where no file was, which a failure removes.
     let created = [];
+    // The previous copies left in a user config directory the tool no longer reads, removed once the
+    // plan is in place: a failure restores their lockfile entries, which still point at them.
+    const movedCopies = [];
     try {
         for (const entry of supportedEntries) {
             created = [];
-            const { lockfile: updatedLockfile, result, sharedEntries, } = await installAsset(entry, options, managedPaths, managedEntries, ownersElsewhere, lockfile, created);
+            const { lockfile: updatedLockfile, movedCopy, result, sharedEntries, } = await installAsset(entry, options, managedPaths, managedEntries, ownersElsewhere, lockfile, created);
             results.push(result);
+            if (movedCopy)
+                movedCopies.push({ previous: movedCopy, written: result.filesPlaced.map((f) => f.destination) });
             // 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);
@@ -209,6 +234,13 @@ export async function executeInstallPlan(plan, options) {
         }
         throw new InstallPlanError(failed, error, added.length);
     }
+    for (const { previous, written } of movedCopies) {
+        await removePlacedFiles(previous, adapterAsPlaced(options.adapter, previous), options.projectDir, {
+            keep: written,
+            lockfile,
+            onProgress: options.onProgress,
+        });
+    }
     return results;
 }
 /**
@@ -285,10 +317,13 @@ export async function rollBackInstalledAssets(installed, before, lockfile, optio
                     kept.add(entry.key);
                     continue;
                 }
-                const configPath = join(options.projectDir, entry.file);
+                const configPath = fromRoot(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);
+                const lockFile = configLockPath(placement, options.projectDir, entry.file);
+                await withConfigLock(lockFile, () => revertConfigEntry(configPath, entry.key, entry.command, format, created, options.onProgress, {
+                    atomic: lockFile !== undefined,
+                }));
             }
             catch (error) {
                 options.onProgress?.(`Warning: Failed to revert config entry ${entry.key} during rollback — ${errorMessage(error)}`);
@@ -303,7 +338,7 @@ export async function rollBackInstalledAssets(installed, before, lockfile, optio
         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);
+            await removeFromEnabledList(fromRoot(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
@@ -377,7 +412,7 @@ function buildManagedEntries(lockfile, projectDir, 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);
+            addOwner(entries, sharedEntryKey({ file: fromRoot(projectDir, entry.file), key: entry.key }), asset);
         }
     }
     return entries;
@@ -387,15 +422,25 @@ function buildManagedEntries(lockfile, projectDir, adapter) {
  * 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 buildManagedPaths(lockfile, projectDir, adapter) {
+async function buildManagedPaths(lockfile, projectDir, adapter) {
     const paths = new Map();
     for (const asset of lockfile.assets ?? []) {
         // Uninstalled for this tool, or a hook never placed by it: a file at its path is not ATK's.
         if (isExcludedForTool(asset, adapter.tool))
             continue;
-        const resolved = resolveInstalledPaths(asset, adapter, projectDir);
+        const resolved = resolveInstalledPaths(asset, adapterAsPlaced(adapter, asset), projectDir);
         for (const file of resolved.files) {
-            addOwner(paths, join(projectDir, file.installedPath), asset);
+            addOwner(paths, fromRoot(projectDir, file.installedPath), asset);
+        }
+        // Its tool's user config directory moved since (the user moved or copied it): a file in the
+        // new one that holds what ATK placed is the asset's own copy, so moving the asset there may
+        // write over it. Any other file there is not ATK's.
+        if (configDirMove(adapter, asset)) {
+            for (const file of resolveInstalledPaths(asset, adapter, projectDir).files) {
+                const path = fromRoot(projectDir, file.installedPath);
+                if (await verifyChecksum(path, file.checksum).catch(() => false))
+                    addOwner(paths, path, asset);
+            }
         }
     }
     return paths;
@@ -578,7 +623,7 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
     // 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)
+        ? resolveConfigFormat(fromRoot(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.
@@ -687,7 +732,7 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
         }
         // The tool runs a registered hook script directly, so it needs the exec bit.
         const scriptPath = hookScriptPath(placement, asset.name);
-        const scriptDest = scriptPath ? join(basePath, scriptPath) : undefined;
+        const scriptDest = scriptPath ? fromRoot(basePath, scriptPath) : undefined;
         if (scriptDest && filesPlaced.some((f) => f.destination === scriptDest)) {
             await makeExecutable(scriptDest);
         }
@@ -698,17 +743,20 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
     // 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))
+        .map((file) => fromRoot(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 = [];
+    // A config file the tool rewrites while it runs is written under its lock, through a rename.
+    const lockFile = placement.configFile ? configLockPath(placement, basePath, placement.configFile) : undefined;
+    const writeOptions = { atomic: lockFile !== undefined };
     // 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
         // command derived from the installed script path.
-        const command = deriveHookCommand(placement.configCommandPrefix, placement.path.replace(/\{name\}/g, asset.name));
-        const hookEntries = await mergeHookConfig(join(basePath, placement.configFile), placement.configKey, configFormat, entry.versionData.hookConfig, command, projectDir, onProgress);
+        const { configFile, configKey } = placement;
+        const hookEntries = await withConfigLock(lockFile, () => mergeHookConfig(fromRoot(basePath, configFile), configKey, configFormat, entry.versionData.hookConfig, hookCommand(placement, asset.name), projectDir, onProgress, writeOptions));
         configEntries.push(...hookEntries);
     }
     else if (placement.configFile && placement.configKey) {
@@ -717,16 +765,18 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
             // (e.g. a whole .mcp.json). Merge the entries inside content[configKey] into
             // configFile[configKey] keyed by each entry's own name, instead of nesting the
             // whole content under the asset name.
-            const { entries, names } = await mergeFragmentConfig(join(basePath, placement.configFile), placement.configKey, configFormat, projectDir, mergeContent, placement.configFragmentKey, onProgress);
+            const { configCommandEntryDefaults, configEntryDefaults, configFile, configFragmentKey, configKey } = placement;
+            const { entries, names } = await withConfigLock(lockFile, () => mergeFragmentConfig(fromRoot(basePath, configFile), configKey, configFormat, projectDir, mergeContent, configFragmentKey, onProgress, writeOptions, configEntryDefaults, configCommandEntryDefaults));
             configEntries.push(...entries);
             // 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) {
-                enabledListAdded = await addToEnabledList(join(basePath, placement.enabledListFile), placement.enabledListKey, names, onProgress);
+                enabledListAdded = await addToEnabledList(fromRoot(basePath, placement.enabledListFile), placement.enabledListKey, names, onProgress);
             }
         }
         else {
-            const configResult = await updateConfigFile(join(basePath, placement.configFile), placement.configKey, configFormat, asset.name, asset.type, projectDir, mergeContent, onProgress);
+            const { configFile, configKey } = placement;
+            const configResult = await withConfigLock(lockFile, () => updateConfigFile(fromRoot(basePath, configFile), configKey, configFormat, asset.name, asset.type, projectDir, mergeContent, onProgress, writeOptions));
             if (configResult) {
                 configEntries.push(configResult);
             }
@@ -736,10 +786,21 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
     const configFilesCreated = absentConfigFiles
         .filter((path) => existsSync(path))
         .map((path) => toRelativePosix(projectDir, path));
+    const previousEntry = (lockfile.assets ?? []).find((a) => a.name === asset.name && a.type === asset.type && a.org === entry.asset.org);
+    // Only once the asset is registered where the placement says: a merge that failed (it warns and
+    // writes nothing) must not take away the old entry as well.
+    if (configEntries.length > 0) {
+        await removeMovedConfigEntries(previousEntry, adapter, placement, lockfile, projectDir, onProgress);
+    }
+    // The tool's user config directory moved since the previous copy was placed (`install --force`,
+    // another version, a reinstall): this one is where the tool reads it now, so the old copy's files
+    // go too, once the whole plan is in place (see executeInstallPlan).
+    const movedCopy = previousEntry && !isExcludedForTool(previousEntry, adapter.tool) && configDirMove(adapter, previousEntry)
+        ? previousEntry
+        : undefined;
     // 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.
-    const previousEntry = (lockfile.assets ?? []).find((a) => a.name === asset.name && a.type === asset.type && a.org === entry.asset.org);
     const lockfileConfigEntries = mergeConfigEntriesForTool(previousEntry, adapter, configEntries);
     // Installing for a tool re-includes it; exclusions recorded for other tools carry over.
     const exclusions = carryExclusions(previousEntry, adapter.tool);
@@ -753,6 +814,8 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
             ? previousEntry.pinnedVersion
             : undefined;
     const bundleOrigin = bundleOriginFor(previousEntry, options.bundleOrigin);
+    // Where this tool's user config directory is, so its copy is found there once the directory moves.
+    const userConfigDirs = recordUserConfigDir(previousEntry?.userConfigDirs, adapter);
     // Update lockfile — use resolved version and per-version dependency data
     const installedAsset = {
         ...(bundleOrigin ? { bundleOrigin } : {}),
@@ -772,6 +835,7 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
         ...(pinnedVersion ? { pinnedVersion } : {}),
         type: asset.type,
         ...(exclusions.undeclaredTools ? { undeclaredTools: exclusions.undeclaredTools } : {}),
+        ...(userConfigDirs ? { userConfigDirs } : {}),
         version: entry.version,
     };
     const updatedLockfile = addAssetToLockfile(lockfile, installedAsset);
@@ -779,6 +843,7 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
     onProgress?.(`Installed ${asset.name}@${entry.version}`);
     return {
         lockfile: updatedLockfile,
+        ...(movedCopy ? { movedCopy } : {}),
         result: {
             ...(blockWritten ? { blockWritten } : {}),
             ...(bundleOrigin ? { bundleOrigin } : {}),
@@ -805,7 +870,7 @@ function isRecord(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)),
+        file: fromRoot(basePath, placement.path.replace(/\{name\}/g, name)),
         key: `ATK:${name}`,
         label: `"${name}" block`,
     };
@@ -819,9 +884,12 @@ function memoryTemplateBlock(placement, name, basePath) {
  * 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 entries are found by {@link fragmentEntries}.
+ * The entries are found by {@link fragmentEntries}. `entryDefaults` (the placement's
+ * `configEntryDefaults`) fills in the keys an entry leaves out, and `commandEntryDefaults`
+ * (`configCommandEntryDefaults`) those of an entry with a `command`, a local stdio server; the
+ * entry's own keys win.
  */
-async function mergeFragmentConfig(configFilePath, configKey, format, projectDir, mergeContent, fragmentKey, onProgress) {
+async function mergeFragmentConfig(configFilePath, configKey, format, projectDir, mergeContent, fragmentKey, onProgress, writeOptions = {}, entryDefaults = {}, commandEntryDefaults = {}) {
     const empty = { entries: [], names: [] };
     if (!mergeContent) {
         return empty;
@@ -846,8 +914,10 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
         }
         const section = config[configKey];
         const entries = [];
+        const commandDefaults = { ...entryDefaults, ...commandEntryDefaults };
         for (const [name, fragment] of inner) {
-            const value = normalizeForFormat({ ...fragment, _managedBy: 'atk' }, format);
+            const defaults = 'command' in fragment ? commandDefaults : entryDefaults;
+            const value = normalizeForFormat({ ...defaults, ...fragment, _managedBy: 'atk' }, format);
             section[name] = value;
             entries.push({
                 checksum: computeConfigEntryChecksum(value),
@@ -855,7 +925,7 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
                 key: `${configKey}.${name}`,
             });
         }
-        await writeConfigFile(configFilePath, config, format, onProgress);
+        await writeConfigFile(configFilePath, config, format, onProgress, writeOptions);
         return { entries, names: inner.map(([name]) => name) };
     }
     catch (error) {
@@ -874,7 +944,7 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
  * owned by this command is dropped before appending, so repeated install/sync doesn't duplicate.
  * Returns one lockfile config entry per event, checksummed over the ATK-owned group only.
  */
-async function mergeHookConfig(configFilePath, configKey, format, hookConfig, command, projectDir, onProgress) {
+async function mergeHookConfig(configFilePath, configKey, format, hookConfig, command, projectDir, onProgress, writeOptions = {}) {
     const events = hookConfig ? Object.keys(hookConfig) : [];
     if (events.length === 0) {
         // No hookConfig (e.g. legacy asset or un-rebuilt registry index) — write nothing.
@@ -910,7 +980,7 @@ async function mergeHookConfig(configFilePath, configKey, format, hookConfig, co
                 key: `${configKey}.${event}`,
             });
         }
-        await writeConfigFile(configFilePath, config, format, onProgress);
+        await writeConfigFile(configFilePath, config, format, onProgress, writeOptions);
         return entries;
     }
     catch (error) {
@@ -943,12 +1013,37 @@ function plannedSharedEntries(name, type, placement, basePath, mergeContent) {
         ...entries,
         ...names.map((entryName) => ({
             entry: { name: entryName, section: configKey },
-            file: join(basePath, configFile),
+            file: fromRoot(basePath, configFile),
             key: `${configKey}.${entryName}`,
             label: `"${configKey}.${entryName}" entry`,
         })),
     ];
 }
+/**
+ * Remove the config entries `previous` recorded for the adapter's tool in a file other than the
+ * placement's `configFile`. An adapter that moved its config file (copilot-cli's mcp-config, from
+ * `copilot/mcp-config.json` to `.vscode/mcp.json`) left them where the tool doesn't read them, and
+ * this install has just registered the asset where it does. As with an uninstall, an entry holding
+ * the value of another asset that owns it stays, for that asset's own sync to move. A file left
+ * empty is deleted. (`atk sync` removes the asset before reinstalling it, so there it finds the
+ * entries gone already; it is `install` and `update` that need it.)
+ */
+async function removeMovedConfigEntries(previous, adapter, placement, lockfile, projectDir, onProgress) {
+    if (!previous || !placement.configFile)
+        return;
+    const configFile = normalizeConfigPath(placement.configFile);
+    const moved = getConfigEntriesForTool(previous, adapter).filter((e) => normalizeConfigPath(e.file) !== configFile);
+    if (moved.length === 0)
+        return;
+    const owners = configEntriesOwnedByOthers(lockfile, previous, adapter, projectDir);
+    for (const entry of moved) {
+        const configPath = fromRoot(projectDir, entry.file);
+        if (await holdsAnotherOwnersValue(entry, owners, projectDir))
+            continue;
+        // The old file's own format: the placement's describes the file it uses now.
+        await revertConfigEntry(configPath, entry.key, entry.command, resolveConfigFormat(configPath), true, onProgress);
+    }
+}
 /**
  * Resolve the destination file path for an asset file.
  * For directory-based placement (entrypointName set), the path is a directory template.
@@ -959,18 +1054,18 @@ function resolveFilePath(pathTemplate, assetName, basePath, relativePath, assetT
     const resolvedTemplate = pathTemplate.replace(/\{name\}/g, assetName);
     if (entrypointName) {
         // Directory-based placement: path is a directory, entrypoint gets the fixed name
-        const dirPath = resolvedTemplate;
+        const dirPath = fromRoot(basePath, resolvedTemplate);
         if (isEntrypoint(relativePath, assetType, declaredEntrypoint)) {
-            return join(basePath, dirPath, entrypointName);
+            return join(dirPath, entrypointName);
         }
-        return join(basePath, dirPath, relativePath);
+        return join(dirPath, relativePath);
     }
     // Default: single-file placement
-    const templateDir = dirname(resolvedTemplate);
+    const templatePath = fromRoot(basePath, resolvedTemplate);
     if (isEntrypoint(relativePath, assetType, declaredEntrypoint)) {
-        return join(basePath, resolvedTemplate);
+        return templatePath;
     }
-    return join(basePath, templateDir, relativePath);
+    return join(dirname(templatePath), relativePath);
 }
 /**
  * Revert a config file entry created during installation.
@@ -978,7 +1073,7 @@ function resolveFilePath(pathTemplate, assetName, basePath, relativePath, assetT
  * 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, deleteWhenEmpty, onProgress) {
+async function revertConfigEntry(configFilePath, keyPath, command, format, deleteWhenEmpty, onProgress, writeOptions = {}) {
     if (!existsSync(configFilePath)) {
         return;
     }
@@ -1009,10 +1104,10 @@ async function revertConfigEntry(configFilePath, keyPath, command, format, delet
             }
         }
         if (deleteWhenEmpty && Object.keys(config).length === 0) {
-            await unlink(configFilePath);
+            await removeEmptiedConfigFile(configFilePath, format, writeOptions);
             return;
         }
-        await writeConfigFile(configFilePath, config, format, onProgress);
+        await writeConfigFile(configFilePath, config, format, onProgress, writeOptions);
     }
     catch (error) {
         onProgress?.(`Warning: Failed to revert config entry ${keyPath} in ${configFilePath} — ${errorMessage(error)}`);
@@ -1024,7 +1119,7 @@ async function revertConfigEntry(configFilePath, keyPath, command, format, delet
  * created it.
  */
 async function revertMemoryBlock(projectDir, assetName, { created, file, replaced }, onProgress) {
-    const path = join(projectDir, file);
+    const path = fromRoot(projectDir, file);
     try {
         if (!existsSync(path))
             return;
@@ -1062,14 +1157,15 @@ function stripAtkBlock(content, assetName) {
  * The refusal of a plan that none of `tools` installs anything of because it holds a hook whose
  * manifest declares none of them; undefined when the plan has no such hook.
  */
-function undeclaredHookError(plan, tools) {
+function undeclaredHookError(plan, tools, scope) {
     const hook = plan.entries.find((entry) => entry.asset.type === 'hook' && !tools.some((tool) => declaresTool(entry.versionData.tools, tool)));
     if (!hook)
         return undefined;
+    const setup = scopedCommand('atk setup', scope);
     return new InstallerError(`Hook "${formatOrgName(hook.asset.org, hook.asset.name)}" is for ${hook.versionData.tools.join(', ')} only, ` +
         `so it is not installed for ${tools.join(', ')}.`, {
-        command: 'atk setup',
-        hint: 'A hook is installed only for the tools its manifest lists. Add one with `atk setup`, or install it in a project set up for one.',
+        command: setup,
+        hint: `A hook is installed only for the tools its manifest lists. Add one with \`${setup}\`, or install it in a project set up for one.`,
     });
 }
 /**
@@ -1077,7 +1173,7 @@ function undeclaredHookError(plan, tools) {
  * When mergeContent is provided, it is merged into the config section with _managedBy marker.
  * Otherwise, a simple marker is written.
  */
-async function updateConfigFile(configFilePath, configKey, format, assetName, assetType, projectDir, mergeContent, onProgress) {
+async function updateConfigFile(configFilePath, configKey, format, assetName, assetType, projectDir, mergeContent, onProgress, writeOptions = {}) {
     try {
         let config = {};
         if (existsSync(configFilePath)) {
@@ -1108,7 +1204,7 @@ async function updateConfigFile(configFilePath, configKey, format, assetName, as
                 type: assetType,
             };
         }
-        await writeConfigFile(configFilePath, config, format, onProgress);
+        await writeConfigFile(configFilePath, config, format, onProgress, writeOptions);
         const checksum = computeConfigEntryChecksum(section[assetName]);
         return { checksum, file: toRelativePosix(projectDir, configFilePath), key: `${configKey}.${assetName}` };
     }