@detergent-software/atk 9.4.0-dev.9 → 9.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/CHANGELOG.md +391 -0
  2. package/README.md +7 -2
  3. package/build/command-manifest.json +33 -7
  4. package/build/commands/_app.d.ts.map +1 -1
  5. package/build/commands/_app.js +4 -2
  6. package/build/commands/_app.js.map +1 -1
  7. package/build/commands/audit.d.ts.map +1 -1
  8. package/build/commands/audit.js +7 -4
  9. package/build/commands/audit.js.map +1 -1
  10. package/build/commands/diff.d.ts.map +1 -1
  11. package/build/commands/diff.js +10 -10
  12. package/build/commands/diff.js.map +1 -1
  13. package/build/commands/doctor.d.ts.map +1 -1
  14. package/build/commands/doctor.js +1 -1
  15. package/build/commands/doctor.js.map +1 -1
  16. package/build/commands/info.d.ts.map +1 -1
  17. package/build/commands/info.js +16 -14
  18. package/build/commands/info.js.map +1 -1
  19. package/build/commands/init.d.ts.map +1 -1
  20. package/build/commands/init.js +1 -1
  21. package/build/commands/init.js.map +1 -1
  22. package/build/commands/install.d.ts.map +1 -1
  23. package/build/commands/install.js +127 -69
  24. package/build/commands/install.js.map +1 -1
  25. package/build/commands/move.d.ts.map +1 -1
  26. package/build/commands/move.js +5 -4
  27. package/build/commands/move.js.map +1 -1
  28. package/build/commands/outdated.js +1 -1
  29. package/build/commands/outdated.js.map +1 -1
  30. package/build/commands/sync.d.ts.map +1 -1
  31. package/build/commands/sync.js +6 -4
  32. package/build/commands/sync.js.map +1 -1
  33. package/build/commands/update.d.ts +1 -1
  34. package/build/commands/update.d.ts.map +1 -1
  35. package/build/commands/update.js +1 -1
  36. package/build/commands/update.js.map +1 -1
  37. package/build/commands/upgrade.d.ts +16 -0
  38. package/build/commands/upgrade.d.ts.map +1 -0
  39. package/build/commands/upgrade.js +64 -0
  40. package/build/commands/upgrade.js.map +1 -0
  41. package/build/commands/why.d.ts.map +1 -1
  42. package/build/commands/why.js +28 -7
  43. package/build/commands/why.js.map +1 -1
  44. package/build/components/DiffView.d.ts +3 -1
  45. package/build/components/DiffView.d.ts.map +1 -1
  46. package/build/components/DiffView.js +18 -4
  47. package/build/components/DiffView.js.map +1 -1
  48. package/build/components/EnabledEntriesHint.d.ts +14 -0
  49. package/build/components/EnabledEntriesHint.d.ts.map +1 -0
  50. package/build/components/EnabledEntriesHint.js +13 -0
  51. package/build/components/EnabledEntriesHint.js.map +1 -0
  52. package/build/components/InitSuccess.d.ts.map +1 -1
  53. package/build/components/InitSuccess.js +4 -1
  54. package/build/components/InitSuccess.js.map +1 -1
  55. package/build/components/InstallSummary.d.ts +7 -2
  56. package/build/components/InstallSummary.d.ts.map +1 -1
  57. package/build/components/InstallSummary.js +3 -1
  58. package/build/components/InstallSummary.js.map +1 -1
  59. package/build/components/LeftoverFilesHint.d.ts +21 -0
  60. package/build/components/LeftoverFilesHint.d.ts.map +1 -0
  61. package/build/components/LeftoverFilesHint.js +13 -0
  62. package/build/components/LeftoverFilesHint.js.map +1 -0
  63. package/build/components/index.d.ts +2 -0
  64. package/build/components/index.d.ts.map +1 -1
  65. package/build/components/index.js +2 -0
  66. package/build/components/index.js.map +1 -1
  67. package/build/hooks/useInitState.d.ts +9 -1
  68. package/build/hooks/useInitState.d.ts.map +1 -1
  69. package/build/hooks/useInitState.js +52 -10
  70. package/build/hooks/useInitState.js.map +1 -1
  71. package/build/hooks/useListActions.d.ts.map +1 -1
  72. package/build/hooks/useListActions.js +4 -1
  73. package/build/hooks/useListActions.js.map +1 -1
  74. package/build/hooks/useUninstallState.d.ts.map +1 -1
  75. package/build/hooks/useUninstallState.js +46 -23
  76. package/build/hooks/useUninstallState.js.map +1 -1
  77. package/build/lib/adapter.d.ts +14 -9
  78. package/build/lib/adapter.d.ts.map +1 -1
  79. package/build/lib/adapter.js +46 -8
  80. package/build/lib/adapter.js.map +1 -1
  81. package/build/lib/api-client.d.ts.map +1 -1
  82. package/build/lib/api-client.js +2 -1
  83. package/build/lib/api-client.js.map +1 -1
  84. package/build/lib/asset-tools.d.ts +8 -0
  85. package/build/lib/asset-tools.d.ts.map +1 -1
  86. package/build/lib/asset-tools.js +14 -0
  87. package/build/lib/asset-tools.js.map +1 -1
  88. package/build/lib/completion/candidates.d.ts.map +1 -1
  89. package/build/lib/completion/candidates.js +21 -8
  90. package/build/lib/completion/candidates.js.map +1 -1
  91. package/build/lib/config-entries.d.ts +3 -3
  92. package/build/lib/config-entries.d.ts.map +1 -1
  93. package/build/lib/config-entries.js +16 -6
  94. package/build/lib/config-entries.js.map +1 -1
  95. package/build/lib/config-lock.d.ts +2 -1
  96. package/build/lib/config-lock.d.ts.map +1 -1
  97. package/build/lib/config-lock.js +10 -2
  98. package/build/lib/config-lock.js.map +1 -1
  99. package/build/lib/cross-scope.d.ts +6 -2
  100. package/build/lib/cross-scope.d.ts.map +1 -1
  101. package/build/lib/cross-scope.js +20 -13
  102. package/build/lib/cross-scope.js.map +1 -1
  103. package/build/lib/diagnostics.d.ts +3 -2
  104. package/build/lib/diagnostics.d.ts.map +1 -1
  105. package/build/lib/diagnostics.js +11 -11
  106. package/build/lib/diagnostics.js.map +1 -1
  107. package/build/lib/diff-command.d.ts +9 -3
  108. package/build/lib/diff-command.d.ts.map +1 -1
  109. package/build/lib/diff-command.js +58 -21
  110. package/build/lib/diff-command.js.map +1 -1
  111. package/build/lib/diff.d.ts +8 -4
  112. package/build/lib/diff.d.ts.map +1 -1
  113. package/build/lib/diff.js +23 -4
  114. package/build/lib/diff.js.map +1 -1
  115. package/build/lib/doctor-fix.d.ts +8 -3
  116. package/build/lib/doctor-fix.d.ts.map +1 -1
  117. package/build/lib/doctor-fix.js +50 -3
  118. package/build/lib/doctor-fix.js.map +1 -1
  119. package/build/lib/enabled-list.d.ts +7 -3
  120. package/build/lib/enabled-list.d.ts.map +1 -1
  121. package/build/lib/enabled-list.js +7 -5
  122. package/build/lib/enabled-list.js.map +1 -1
  123. package/build/lib/gitignore.d.ts +8 -0
  124. package/build/lib/gitignore.d.ts.map +1 -1
  125. package/build/lib/gitignore.js +51 -6
  126. package/build/lib/gitignore.js.map +1 -1
  127. package/build/lib/hook-config.d.ts +90 -7
  128. package/build/lib/hook-config.d.ts.map +1 -1
  129. package/build/lib/hook-config.js +135 -11
  130. package/build/lib/hook-config.js.map +1 -1
  131. package/build/lib/hook-script.d.ts +45 -0
  132. package/build/lib/hook-script.d.ts.map +1 -1
  133. package/build/lib/hook-script.js +118 -1
  134. package/build/lib/hook-script.js.map +1 -1
  135. package/build/lib/init.d.ts +34 -12
  136. package/build/lib/init.d.ts.map +1 -1
  137. package/build/lib/init.js +180 -32
  138. package/build/lib/init.js.map +1 -1
  139. package/build/lib/install-targets.d.ts +20 -6
  140. package/build/lib/install-targets.d.ts.map +1 -1
  141. package/build/lib/install-targets.js +65 -8
  142. package/build/lib/install-targets.js.map +1 -1
  143. package/build/lib/installer.d.ts +15 -5
  144. package/build/lib/installer.d.ts.map +1 -1
  145. package/build/lib/installer.js +201 -41
  146. package/build/lib/installer.js.map +1 -1
  147. package/build/lib/local-edits.d.ts +15 -2
  148. package/build/lib/local-edits.d.ts.map +1 -1
  149. package/build/lib/local-edits.js +40 -13
  150. package/build/lib/local-edits.js.map +1 -1
  151. package/build/lib/lockfile.d.ts +2 -2
  152. package/build/lib/lockfile.js +4 -4
  153. package/build/lib/lockfile.js.map +1 -1
  154. package/build/lib/mover.d.ts +5 -4
  155. package/build/lib/mover.d.ts.map +1 -1
  156. package/build/lib/mover.js +43 -35
  157. package/build/lib/mover.js.map +1 -1
  158. package/build/lib/multi-tool-install.d.ts +28 -5
  159. package/build/lib/multi-tool-install.d.ts.map +1 -1
  160. package/build/lib/multi-tool-install.js +105 -26
  161. package/build/lib/multi-tool-install.js.map +1 -1
  162. package/build/lib/named-entry.d.ts +12 -0
  163. package/build/lib/named-entry.d.ts.map +1 -1
  164. package/build/lib/named-entry.js +16 -8
  165. package/build/lib/named-entry.js.map +1 -1
  166. package/build/lib/notices.d.ts +2 -0
  167. package/build/lib/notices.d.ts.map +1 -1
  168. package/build/lib/notices.js +10 -0
  169. package/build/lib/notices.js.map +1 -1
  170. package/build/lib/schemas/adapter.d.ts +33 -0
  171. package/build/lib/schemas/adapter.d.ts.map +1 -1
  172. package/build/lib/schemas/adapter.js +31 -5
  173. package/build/lib/schemas/adapter.js.map +1 -1
  174. package/build/lib/self-upgrade.d.ts +66 -0
  175. package/build/lib/self-upgrade.d.ts.map +1 -0
  176. package/build/lib/self-upgrade.js +183 -0
  177. package/build/lib/self-upgrade.js.map +1 -0
  178. package/build/lib/sync.d.ts +39 -0
  179. package/build/lib/sync.d.ts.map +1 -1
  180. package/build/lib/sync.js +181 -10
  181. package/build/lib/sync.js.map +1 -1
  182. package/build/lib/touched-paths.d.ts.map +1 -1
  183. package/build/lib/touched-paths.js +2 -1
  184. package/build/lib/touched-paths.js.map +1 -1
  185. package/build/lib/uninstaller.d.ts +29 -1
  186. package/build/lib/uninstaller.d.ts.map +1 -1
  187. package/build/lib/uninstaller.js +99 -5
  188. package/build/lib/uninstaller.js.map +1 -1
  189. package/build/lib/update-check.d.ts +27 -1
  190. package/build/lib/update-check.d.ts.map +1 -1
  191. package/build/lib/update-check.js +74 -8
  192. package/build/lib/update-check.js.map +1 -1
  193. package/build/lib/updater.d.ts +2 -0
  194. package/build/lib/updater.d.ts.map +1 -1
  195. package/build/lib/updater.js +36 -3
  196. package/build/lib/updater.js.map +1 -1
  197. package/build/lib/version.d.ts +12 -4
  198. package/build/lib/version.d.ts.map +1 -1
  199. package/build/lib/version.js +19 -7
  200. package/build/lib/version.js.map +1 -1
  201. package/package.json +1 -1
  202. package/tool-adapters/claude-code.json +2 -1
  203. package/tool-adapters/codex-cli.json +5 -1
  204. package/tool-adapters/copilot-cli.json +58 -9
@@ -2,17 +2,18 @@ import { existsSync } from 'node:fs';
2
2
  import { mkdir, readFile, unlink } from 'node:fs/promises';
3
3
  import { dirname, join } from 'node:path';
4
4
  import { adapterAsPlaced, checkRealPaths, configDirMove, configEntryPath, getPlacement, isEntrypoint, recordUserConfigDir, resolveInstalledPaths, } from './adapter.js';
5
- import { carryExclusions, declarationAllows, declaresTool, isExcludedForTool, isUninstalledForTool, } from './asset-tools.js';
5
+ import { carryExclusions, declarationAllows, declaresTool, isExcludedForTool, isUninstalledForTool, takesEntrypoint, } from './asset-tools.js';
6
6
  import { computeConfigEntryChecksum, computeHookGroupChecksum, CONFIG_CHECKSUM_VERSION, hashBytes, verifyChecksum, } from './checksum.js';
7
7
  import { getConfigEntriesForTool, getOtherToolsConfigEntries, mergeConfigEntriesForTool, normalizeConfigPath, staleHookCommandEntries, } from './config-entries.js';
8
8
  import { normalizeForFormat, parseConfig, readConfigFile, removeEmptiedConfigFile, resolveConfigFormat, writeConfigFile, } from './config-file.js';
9
9
  import { configLockPath, withConfigLock } from './config-lock.js';
10
10
  import { addToEnabledList, removeFromEnabledList } from './enabled-list.js';
11
11
  import { ApiCodeError, errorGuidance, errorMessage } from './errors.js';
12
- import { ensureGitignoreEntries } from './gitignore.js';
13
- import { buildHookGroup, hookCommand, hookGroupOwnsCommand, isNodeHookEntrypoint, placementForEntrypoint, removeHookGroup, } from './hook-config.js';
14
- import { hookScriptPath, makeExecutable } from './hook-script.js';
12
+ import { ensureGitignoreEntries, removeRetiredGitignoreEntries } from './gitignore.js';
13
+ import { buildHookEntry, hookCommand, hookEventsFor, hookGroupOwnsCommand, hookPowershellCommand, isEmptyHookConfig, isNodeHookEntrypoint, leftOutHookEventReason, placementForAsset, placementForEntrypoint, removeHookGroup, } from './hook-config.js';
14
+ import { hookScriptPath, isGeneratedHookFile, jsonHookFilePath, leftoverHookScripts, makeExecutable, misplacedHookCopy, } from './hook-script.js';
15
15
  import { isInstalledForTool } from './installed-for-tool.js';
16
+ import { isPublishedContent } from './local-edits.js';
16
17
  import { addAssetToLockfile, findInstalledAsset, readLockfile, removeAssetFromLockfile, writeLockfile, } from './lockfile.js';
17
18
  import { formatOrgName } from './org.js';
18
19
  import { configEntriesOwnedByOthers, holdsAnotherOwnersValue, pathsOwnedByOthers } from './owned-paths.js';
@@ -107,6 +108,22 @@ export function assertInstalledByAnyTool(plan, toolResults, scope = 'project') {
107
108
  hint: NO_PROJECT_PLACEMENT_HINT,
108
109
  });
109
110
  }
111
+ /** Why the adapter's tool can't take a hook's entrypoint, as the end of a sentence. */
112
+ export function entrypointMisfit(asset, adapter, entrypoint) {
113
+ const path = placementForEntrypoint(adapter.placements.hook, entrypoint).path.replace(/\{name\}/g, asset.name);
114
+ return `${adapter.displayName} reads ${path} as hook config, and the hook's entrypoint ${entrypoint} is not JSON`;
115
+ }
116
+ /**
117
+ * The refusal of a hook whose entrypoint the adapter's tool can't take (see {@link takesEntrypoint}):
118
+ * alone, or when no other tool of the install placed it.
119
+ */
120
+ export function entrypointRefusal(asset, adapter, entrypoint, scope) {
121
+ const setup = scopedCommand('atk setup', scope);
122
+ return new InstallerError(`Hook "${formatOrgName(asset.org, asset.name)}" is not installed for ${adapter.tool}: ${entrypointMisfit(asset, adapter, entrypoint)}.`, {
123
+ command: setup,
124
+ hint: `Add a tool that runs hook scripts, such as Claude Code, with \`${setup}\`, or install it in a project set up for one.`,
125
+ });
126
+ }
110
127
  /**
111
128
  * Execute a full install plan — install all assets in order.
112
129
  * On partial failure, deletes the files the failing asset wrote where no file was before placing
@@ -143,10 +160,13 @@ export async function executeInstallPlan(plan, options) {
143
160
  // those entries instead of aborting the whole run for that tool. When the tool
144
161
  // supports nothing in the plan, fail loudly so a single-tool install isn't a
145
162
  // silent no-op. A hook whose manifest doesn't declare this tool is skipped the same way, and so
146
- // is a dependency that was uninstalled for this tool.
163
+ // is a dependency that was uninstalled for this tool, and, in a multi-tool install, a hook whose
164
+ // entrypoint this tool can't take (alone, the tool refuses it: see installAsset).
147
165
  const installedBefore = options.installedBefore ?? options.managedFrom ?? lockfile;
148
- const supportedEntries = placeableEntries(plan, options.adapter, installedBefore);
166
+ const skipFiles = options.skipUnsupported ? options.files : undefined;
167
+ const supportedEntries = placeableEntries(plan, options.adapter, installedBefore, skipFiles);
149
168
  for (const entry of plan.entries) {
169
+ const entrypoint = skipFiles?.get(planEntryKey(entry))?.entrypoint;
150
170
  if (!getPlacement(options.adapter, entry.asset.type)) {
151
171
  options.onProgress?.(options.scope === 'user'
152
172
  ? `Skipping ${entry.asset.name}: ${options.adapter.displayName} has no user-level ${entry.asset.type}`
@@ -156,6 +176,9 @@ export async function executeInstallPlan(plan, options) {
156
176
  const tools = entry.versionData.tools.join(', ');
157
177
  options.onProgress?.(`Skipping ${entry.asset.name}: the hook is for ${tools} only, not ${options.adapter.tool}`);
158
178
  }
179
+ else if (!takesEntrypoint(options.adapter, entry.asset.type, entrypoint)) {
180
+ options.onProgress?.(`Skipping ${entry.asset.name}: ${entrypointMisfit(entry.asset, options.adapter, entrypoint)}`);
181
+ }
159
182
  else if (!supportedEntries.includes(entry)) {
160
183
  options.onProgress?.(`Skipping ${entry.asset.name}: it was uninstalled for ${options.adapter.tool}`);
161
184
  }
@@ -181,11 +204,16 @@ export async function executeInstallPlan(plan, options) {
181
204
  // The previous copies left in a user config directory the tool no longer reads, removed once the
182
205
  // plan is in place: a failure restores their lockfile entries, which still point at them.
183
206
  const movedCopies = [];
207
+ // The scripts a hook's script version left beside the JSON its new version placed, removed once
208
+ // the plan is in place, with the files of the copies it replaced.
209
+ const leftovers = [];
184
210
  try {
185
211
  for (const entry of supportedEntries) {
186
212
  created = [];
187
- const { lockfile: updatedLockfile, movedCopy, result, sharedEntries, } = await installAsset(entry, options, managedPaths, managedEntries, ownersElsewhere, lockfile, created);
213
+ const { leftoverScripts, lockfile: updatedLockfile, movedCopy, result, sharedEntries, } = await installAsset(entry, options, managedPaths, managedEntries, ownersElsewhere, lockfile, created);
188
214
  results.push(result);
215
+ const dropping = `${formatOrgName(entry.asset.org, entry.asset.name)}@${entry.version}`;
216
+ leftovers.push(...leftoverScripts.map((path) => ({ dropping, path })));
189
217
  if (movedCopy)
190
218
  movedCopies.push({ previous: movedCopy, written: result.filesPlaced.map((f) => f.destination) });
191
219
  // A later entry of this plan may land on these files or entries, and must see whose they are.
@@ -278,6 +306,28 @@ export async function executeInstallPlan(plan, options) {
278
306
  `placed that this install replaced — ${errorMessage(error)}`);
279
307
  }
280
308
  }
309
+ for (const { dropping, path } of leftovers) {
310
+ if (!existsSync(path))
311
+ continue;
312
+ try {
313
+ await unlink(path);
314
+ options.onProgress?.(`Removed ${toRelativePosix(options.projectDir, path)}: ${dropping} no longer ships it`);
315
+ }
316
+ catch (error) {
317
+ options.onProgress?.(`Warning: Failed to remove ${path}, which ${dropping} no longer ships — ${errorMessage(error)}`);
318
+ }
319
+ }
320
+ lockfile = await recordUninstalledDependencies(plan, supportedEntries, lockfile, options, skipFiles);
321
+ // A config file the adapter no longer uses stops being ignored once this plan has moved ATK's
322
+ // entries out of it, and not before.
323
+ if (options.scope !== 'user') {
324
+ try {
325
+ await removeRetiredGitignoreEntries(options.projectDir, options.adapter, lockfile);
326
+ }
327
+ catch {
328
+ options.onProgress?.('Warning: Failed to update .gitignore — continuing with install');
329
+ }
330
+ }
281
331
  return results;
282
332
  }
283
333
  /**
@@ -290,11 +340,11 @@ export async function executeInstallPlan(plan, options) {
290
340
  *
291
341
  * `downloaded` is shared by the passes of a multi-tool update or sync, whose plans differ by tool:
292
342
  * an entry it holds is not downloaded again, and the entries this call downloads are added to it.
293
- * With `installedBefore`, a dependency no tool places because it was uninstalled for each of them
294
- * is not downloaded (see {@link placeableEntries}).
343
+ * A dependency uninstalled for the tools is downloaded too: its lockfile entry still moves to the
344
+ * plan's version (see {@link recordUninstalledDependencies}).
295
345
  */
296
- export async function fetchPlanFiles(plan, adapters, downloaded, installedBefore) {
297
- const placeable = new Set(adapters.flatMap((adapter) => placeableEntries(plan, adapter, installedBefore)));
346
+ export async function fetchPlanFiles(plan, adapters, downloaded) {
347
+ const placeable = new Set(adapters.flatMap((adapter) => placeableEntries(plan, adapter)));
298
348
  const ordered = plan.entries.filter((entry) => placeable.has(entry));
299
349
  const missing = ordered.filter((entry) => !downloaded?.has(planEntryKey(entry)));
300
350
  const limit = createLimiter(FILE_DOWNLOAD_CONCURRENCY);
@@ -341,19 +391,27 @@ export function installFailureMessage(error, asset) {
341
391
  * `installedBefore`, also less the `dependency` entries it records as uninstalled for the tool,
342
392
  * which `atk sync` would not place there either; a `direct` entry is placed again. (An update
343
393
  * carries the asset's own install reason onto its entry, but skips an asset uninstalled for the
344
- * tool before it plans.)
394
+ * tool before it plans.) With the plan's downloaded `files`, also less the hooks whose entrypoint
395
+ * the tool can't take (see {@link takesEntrypoint}).
345
396
  */
346
- export function placeableEntries(plan, adapter, installedBefore) {
347
- return plan.entries.filter(({ asset, reason, versionData }) => {
397
+ export function placeableEntries(plan, adapter, installedBefore, files) {
398
+ return plan.entries.filter((entry) => {
399
+ const { asset, reason, versionData } = entry;
348
400
  if (!getPlacement(adapter, asset.type) || !declarationAllows(asset.type, versionData.tools, adapter.tool)) {
349
401
  return false;
350
402
  }
403
+ if (files && !takesEntrypoint(adapter, asset.type, files.get(planEntryKey(entry))?.entrypoint))
404
+ return false;
351
405
  if (reason !== 'dependency' || !installedBefore)
352
406
  return true;
353
407
  const installed = findInstalledAsset(installedBefore, asset.name, asset.type, asset.org);
354
408
  return !installed || !isUninstalledForTool(installed, adapter.tool);
355
409
  });
356
410
  }
411
+ /** The {@link PlanFiles} key of a plan entry: one asset version. */
412
+ export function planEntryKey(entry) {
413
+ return `${entry.asset.type}:${entry.asset.org ?? ''}:${entry.asset.name}@${entry.version}`;
414
+ }
357
415
  /**
358
416
  * Undo the installs of `installed` for the adapter's tool, in reverse order (best-effort): delete
359
417
  * their placed files, revert their config entries (deleting a config file they created once it is
@@ -753,9 +811,16 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
753
811
  assetFiles.some((f) => isNodeHookEntrypoint(f.relativePath))) {
754
812
  throw new InstallerError(`Couldn't read the manifest of "${asset.name}"@${entry.version}, which says how the hook runs, so it wasn't installed.`, { hint: 'Run the command again. If it keeps failing, check the asset in the registry.' });
755
813
  }
756
- const placement = placementForEntrypoint(typePlacement, declaredEntrypoint);
814
+ const placement = placementForAsset(typePlacement, declaredEntrypoint, asset.name);
757
815
  // Find the entrypoint file
758
816
  const entrypointFile = assetFiles.find((f) => isEntrypoint(f.relativePath, asset.type, declaredEntrypoint));
817
+ // A multi-tool install skips such a hook for the tool (see placeableEntries); any other path
818
+ // stops here, before a script is written under the name of the tool's hook config. Without the
819
+ // manifest, the file the filename fallback takes for the entrypoint decides.
820
+ const placedEntrypoint = declaredEntrypoint ?? entrypointFile?.relativePath;
821
+ if (!takesEntrypoint(adapter, asset.type, placedEntrypoint)) {
822
+ throw entrypointRefusal(asset, adapter, placedEntrypoint, options.scope);
823
+ }
759
824
  // Determine merge content for configMerge mode (a keyed merge; a hook merge doesn't use it)
760
825
  let mergeContent;
761
826
  if (placement.configMerge && !placement.configHookMerge && entrypointFile) {
@@ -794,9 +859,39 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
794
859
  : []),
795
860
  ...staleConfigEntries(previousEntry, declaredEntrypoint, adapter, placement).map((stale) => configEntryPath(stale, previousEntry, adapter, projectDir)),
796
861
  ], asset.name, adapter, projectDir);
862
+ // A CLI before ATK-204 wrote a Copilot hook's script under the name of its hook config, and a
863
+ // version whose entrypoint is Copilot's own hook JSON places it there as it is (ATK-818). Either
864
+ // copy is the file this hook's own config is written to now, so it goes once every check has
865
+ // passed; anything else there is left for the check below to refuse, or merged into. Another
866
+ // tool's pass of this run may have recorded the new version already, so the entry from before the
867
+ // run counts too, and a sync over a lockfile a teammate's update wrote has no record of the JSON,
868
+ // so a file a published version shipped counts as well.
869
+ const before = options.installedBefore ?? options.managedFrom;
870
+ const recorded = [previousEntry, before && findInstalledAsset(before, asset.name, asset.type, entry.asset.org)];
871
+ const recordedCommands = recorded.flatMap((e) => e ? getConfigEntriesForTool(e, adapter).flatMap((c) => c.command ?? []) : []);
872
+ const published = (content) => isPublishedContent(entry.asset, Object.keys(entry.asset.versions), content);
873
+ const misplacedCopy = placement.configHookMerge
874
+ ? await misplacedHookCopy(typePlacement, asset.name, recorded, basePath, { published, recorded: recordedCommands })
875
+ : undefined;
876
+ // The other way round, the JSON goes where a script version's hook file is: that file is the
877
+ // asset's own when ATK generated it for this hook, and the script it ran goes once the plan is in
878
+ // place, unless this version or another installed asset places a file there. Another installed
879
+ // hook's entries in that file (a global and an org hook of one name share it) keep it theirs.
880
+ const identity = { name: asset.name, org: entry.asset.org, type: asset.type };
881
+ const generatedHookFile = jsonHookFilePath(typePlacement, declaredEntrypoint, asset.name, basePath);
882
+ const othersInHookFile = !!generatedHookFile &&
883
+ [...configEntriesOwnedByOthers(lockfile, identity, adapter, projectDir).keys()].some((key) => key.startsWith(`${generatedHookFile}#`));
884
+ const ownHookFile = generatedHookFile &&
885
+ !othersInHookFile &&
886
+ (await isGeneratedHookFile(typePlacement, asset.name, generatedHookFile, recordedCommands))
887
+ ? generatedHookFile
888
+ : undefined;
889
+ const scriptsLeft = generatedHookFile
890
+ ? await leftoverHookScripts(typePlacement, asset.name, recorded, basePath, published)
891
+ : [];
797
892
  // A config file the merge below couldn't read fails the install before any file is placed, so a
798
893
  // reinstall's files keep the content its previous entries run.
799
- if (placement.configFile && placement.configKey && !placement.fileless) {
894
+ if (placement.configFile && placement.configKey && !placement.fileless && !misplacedCopy) {
800
895
  await checkConfigReadable(fromRoot(basePath, placement.configFile), configFormat, placement.configHookMerge ? 'the hook' : `"${asset.name}"`);
801
896
  }
802
897
  // Branch on placement type
@@ -873,8 +968,10 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
873
968
  // Default single-file placement
874
969
  const destinations = assetFiles.map((file) => resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, undefined, declaredEntrypoint));
875
970
  if (!force) {
876
- for (const destPath of destinations)
877
- await checkFileConflict(destPath, managedPaths, asset);
971
+ for (const destPath of destinations) {
972
+ if (destPath !== ownHookFile)
973
+ await checkFileConflict(destPath, managedPaths, asset);
974
+ }
878
975
  }
879
976
  checkRealPaths(destinations, asset.name, adapter, projectDir);
880
977
  for (const [index, file] of assetFiles.entries()) {
@@ -921,7 +1018,13 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
921
1018
  // config file as valid event arrays (e.g. settings.json hooks.Stop[]), with the
922
1019
  // command derived from the installed script path.
923
1020
  const { configFile, configKey } = placement;
924
- const hookEntries = await withConfigLock(lockFile, () => mergeHookConfig(fromRoot(basePath, configFile), configKey, configFormat, entry.versionData.hookConfig, hookCommand(placement, asset.name), projectDir, onProgress, writeOptions));
1021
+ if (misplacedCopy)
1022
+ await unlink(misplacedCopy);
1023
+ const { events, leftOut } = hookEventsFor(placement, entry.versionData.hookConfig);
1024
+ for (const left of leftOut) {
1025
+ onProgress?.(`Warning: ${asset.name}'s ${left.event} hook is not registered for ${adapter.tool}: ${leftOutHookEventReason(left, adapter.displayName)}`);
1026
+ }
1027
+ const hookEntries = await withConfigLock(lockFile, () => mergeHookConfig(fromRoot(basePath, configFile), configKey, configFormat, placement, events, hookCommand(placement, asset.name), hookPowershellCommand(placement, asset.name), projectDir, onProgress, writeOptions));
925
1028
  configEntries.push(...hookEntries);
926
1029
  }
927
1030
  else if (placement.configFile && placement.configKey) {
@@ -936,7 +1039,7 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
936
1039
  // Auto-register the merged entry names into an enabled-list (e.g. enabledMcpjsonServers
937
1040
  // in settings.local.json) so the tool auto-approves them.
938
1041
  if (names.length > 0 && placement.enabledListFile && placement.enabledListKey) {
939
- enabledListAdded = await addToEnabledList(fromRoot(basePath, placement.enabledListFile), placement.enabledListKey, names, onProgress);
1042
+ enabledListAdded = await addToEnabledList(fromRoot(basePath, placement.enabledListFile), placement.enabledListKey, names, { disabledListKey: placement.disabledListKey, onProgress });
940
1043
  }
941
1044
  }
942
1045
  else {
@@ -990,11 +1093,7 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
990
1093
  const installedAsset = {
991
1094
  ...(bundleOrigin ? { bundleOrigin } : {}),
992
1095
  ...(lockfileConfigEntries.length > 0 ? { configEntries: lockfileConfigEntries } : {}),
993
- dependencies: (entry.versionData.dependencies ?? []).map((d) => ({
994
- name: d.name,
995
- type: d.type,
996
- ...(d.version ? { version: d.version } : {}),
997
- })),
1096
+ dependencies: lockfileDependencies(entry.versionData),
998
1097
  ...(entry.versionData.description ? { description: entry.versionData.description } : {}),
999
1098
  ...(declaredEntrypoint ? { entrypoint: declaredEntrypoint } : {}),
1000
1099
  ...(exclusions.excludedTools ? { excludedTools: exclusions.excludedTools } : {}),
@@ -1012,6 +1111,8 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
1012
1111
  await writeLockfile(projectDir, updatedLockfile);
1013
1112
  onProgress?.(`Installed ${asset.name}@${entry.version}`);
1014
1113
  return {
1114
+ leftoverScripts: scriptsLeft.filter((path) => !filesPlaced.some((f) => f.destination === path) &&
1115
+ !pathsOwnedByOthers(lockfile, identity, adapter, projectDir).has(path)),
1015
1116
  lockfile: updatedLockfile,
1016
1117
  ...(movedCopy ? { movedCopy } : {}),
1017
1118
  result: {
@@ -1037,6 +1138,14 @@ function isOwner(owners, asset) {
1037
1138
  function isRecord(value) {
1038
1139
  return typeof value === 'object' && value !== null && !Array.isArray(value);
1039
1140
  }
1141
+ /** A version's dependencies as a lockfile entry records them. */
1142
+ function lockfileDependencies(versionData) {
1143
+ return (versionData.dependencies ?? []).map((d) => ({
1144
+ name: d.name,
1145
+ type: d.type,
1146
+ ...(d.version ? { version: d.version } : {}),
1147
+ }));
1148
+ }
1040
1149
  /**
1041
1150
  * `fn` over `items` in order, at most `limit` at a time, settled in the order of `items`. Once one
1042
1151
  * rejects, no further item starts: those it never started are `undefined`, after every started one.
@@ -1130,16 +1239,18 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
1130
1239
  * Merge a hook asset's event bindings into a tool config file (e.g. .claude/settings.json).
1131
1240
  *
1132
1241
  * Claude Code stores hooks as `hooks.<Event>: [ { matcher?, hooks: [{ type:'command', command }] } ]`,
1133
- * an ARRAY shared by every hook bound to that event. For each event in `hookConfig`, this appends
1134
- * one matcher-group whose command is the installed script path. ATK's group is identified by that
1135
- * command (no marker is written — the tool validates group shape). Idempotent: an existing group
1136
- * owned by this command is dropped before appending, so repeated install/sync doesn't duplicate.
1137
- * Returns one lockfile config entry per event, checksummed over the ATK-owned group only.
1242
+ * an ARRAY shared by every hook bound to that event. For each of `events` (the `hookConfig` events
1243
+ * the placement registers, by the tool's names: {@link hookEventsFor}), this appends one entry in
1244
+ * the placement's format ({@link buildHookEntry}) whose command runs the installed script; a Copilot
1245
+ * CLI entry's `powershell` runs `powershellCommand`. ATK's entry is identified by `command` (no
1246
+ * marker is written — the tool validates group shape).
1247
+ * Idempotent: an existing entry owned by this command is dropped before appending, so repeated
1248
+ * install/sync doesn't duplicate. A Copilot CLI hook file gets its `"version": 1` too. Returns one
1249
+ * lockfile config entry per event, checksummed over the ATK-owned entry only.
1138
1250
  */
1139
- async function mergeHookConfig(configFilePath, configKey, format, hookConfig, command, projectDir, onProgress, writeOptions = {}) {
1140
- const events = hookConfig ? Object.keys(hookConfig) : [];
1251
+ async function mergeHookConfig(configFilePath, configKey, format, placement, events, command, powershellCommand, projectDir, onProgress, writeOptions = {}) {
1141
1252
  if (events.length === 0) {
1142
- // No hookConfig (e.g. legacy asset or un-rebuilt registry index) — write nothing.
1253
+ // No hookConfig (e.g. legacy asset or un-rebuilt registry index), or none the tool has — write nothing.
1143
1254
  return [];
1144
1255
  }
1145
1256
  try {
@@ -1153,13 +1264,16 @@ async function mergeHookConfig(configFilePath, configKey, format, hookConfig, co
1153
1264
  await mkdir(dir, { recursive: true });
1154
1265
  }
1155
1266
  }
1267
+ if (placement.configHookFormat === 'copilot' && config['version'] === undefined) {
1268
+ config = { version: 1, ...config };
1269
+ }
1156
1270
  if (!config[configKey] || typeof config[configKey] !== 'object' || Array.isArray(config[configKey])) {
1157
1271
  config[configKey] = {};
1158
1272
  }
1159
1273
  const section = config[configKey];
1160
1274
  const entries = [];
1161
- for (const event of events) {
1162
- const group = buildHookGroup(command, hookConfig[event]);
1275
+ for (const { binding, event } of events) {
1276
+ const group = buildHookEntry(placement, command, binding, powershellCommand);
1163
1277
  const existing = Array.isArray(section[event]) ? section[event] : [];
1164
1278
  // Idempotency: remove any prior group this asset owns before re-appending.
1165
1279
  const next = existing.filter((g) => !hookGroupOwnsCommand(g, command));
@@ -1182,10 +1296,6 @@ async function mergeHookConfig(configFilePath, configKey, format, hookConfig, co
1182
1296
  });
1183
1297
  }
1184
1298
  }
1185
- /** The {@link PlanFiles} key of a plan entry: one asset version. */
1186
- function planEntryKey(entry) {
1187
- return `${entry.asset.type}:${entry.asset.org ?? ''}:${entry.asset.name}@${entry.version}`;
1188
- }
1189
1299
  /**
1190
1300
  * The memory-template block or keyed config entries an asset of `name` and `type` will write: the
1191
1301
  * fragment's own entry names for a fragment merge, the asset name for any other keyed merge. A
@@ -1212,12 +1322,61 @@ function plannedSharedEntries(name, type, placement, basePath, mergeContent) {
1212
1322
  })),
1213
1323
  ];
1214
1324
  }
1325
+ /**
1326
+ * Move the lockfile entries of the `dependency` entries the adapter's tool skipped only because each
1327
+ * was uninstalled for it (see {@link placeableEntries}) to the plan's version, placing nothing: when
1328
+ * every tool of the run skips one, the lockfile still gets the version its dependents need, which
1329
+ * `atk sync` places for the tools that have it (ATK-810). An entry the lockfile already has at that
1330
+ * version, which another tool's pass placed, is left alone; a later pass that places it writes the
1331
+ * entry again, and a multi-tool run that fails puts the entry back (see `restoreRecordedDependencies`
1332
+ * in multi-tool-install). The exclusions, config entries and install reason carry over, and `files`
1333
+ * are the downloaded version's, as placing it for this tool would record them, each with the
1334
+ * `installedPath` the entry had for that file. Returns `lockfile` as written.
1335
+ */
1336
+ async function recordUninstalledDependencies(plan, placed, lockfile, options, skipFiles) {
1337
+ let updated = lockfile;
1338
+ for (const entry of placeableEntries(plan, options.adapter, undefined, skipFiles)) {
1339
+ if (placed.includes(entry))
1340
+ continue;
1341
+ const { asset, version, versionData } = entry;
1342
+ const current = findInstalledAsset(updated, asset.name, asset.type, asset.org);
1343
+ if (!current || current.version === version)
1344
+ continue;
1345
+ const { entrypoint, files } = options.files?.get(planEntryKey(entry)) ?? (await fetchAssetFiles(asset, version, asset.org));
1346
+ const placement = placementForAsset(getPlacement(options.adapter, asset.type), entrypoint, asset.name);
1347
+ const { description: _description, entrypoint: _entrypoint, pinnedVersion: _pinnedVersion, ...kept } = current;
1348
+ // A tool outside the run may still have this copy placed, where its paths say.
1349
+ const installedPaths = new Map(current.files.map((f) => [f.sourcePath, f.installedPath]));
1350
+ updated = addAssetToLockfile(updated, {
1351
+ ...kept,
1352
+ dependencies: lockfileDependencies(versionData),
1353
+ ...(versionData.description ? { description: versionData.description } : {}),
1354
+ ...(entrypoint ? { entrypoint } : {}),
1355
+ files: placement.fileless || asset.type === 'memory-template'
1356
+ ? []
1357
+ : files.map((file) => {
1358
+ const installedPath = installedPaths.get(file.relativePath);
1359
+ return {
1360
+ checksum: hashBytes(file.content),
1361
+ ...(installedPath ? { installedPath } : {}),
1362
+ sourcePath: file.relativePath,
1363
+ };
1364
+ }),
1365
+ version,
1366
+ });
1367
+ options.onProgress?.(`Recorded ${formatOrgName(asset.org, asset.name)}@${version} in the lockfile without placing it: ` +
1368
+ `it was uninstalled for ${options.adapter.tool}`);
1369
+ }
1370
+ if (updated !== lockfile)
1371
+ await writeLockfile(options.projectDir, updated);
1372
+ return updated;
1373
+ }
1215
1374
  /**
1216
1375
  * Remove the config entries `previous` recorded for the adapter's tool that this install has just
1217
1376
  * replaced: those in a file other than the placement's `configFile`, and a hook's groups that run
1218
1377
  * another command than the one just registered ({@link staleHookCommandEntries}). An adapter that
1219
1378
  * moved its config file (copilot-cli's mcp-config, from `copilot/mcp-config.json` to
1220
- * `.vscode/mcp.json`) left them where the tool doesn't read them; a hook placed with project-scope
1379
+ * `.vscode/mcp.json`, then to `.github/mcp.json`) left them where the tool doesn't read them; a hook placed with project-scope
1221
1380
  * rules at the user root left a group the tool would run beside the new one. As with an uninstall,
1222
1381
  * an entry holding the value of another asset that owns it stays, for that asset's own sync to
1223
1382
  * move. A file left empty is deleted. (`atk sync` removes the asset before reinstalling it, so
@@ -1307,7 +1466,8 @@ async function revertConfigEntry(configFilePath, keyPath, command, format, delet
1307
1466
  delete config[sectionKey];
1308
1467
  }
1309
1468
  }
1310
- if (deleteWhenEmpty && Object.keys(config).length === 0) {
1469
+ const empty = command !== undefined ? isEmptyHookConfig(config) : Object.keys(config).length === 0;
1470
+ if (deleteWhenEmpty && empty) {
1311
1471
  await removeEmptiedConfigFile(configFilePath, format, writeOptions);
1312
1472
  return;
1313
1473
  }