@detergent-software/atk 9.4.0-dev.3 → 9.4.0-dev.31

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 (140) hide show
  1. package/CHANGELOG.md +227 -0
  2. package/README.md +2 -2
  3. package/build/command-manifest.json +5 -5
  4. package/build/commands/audit.d.ts.map +1 -1
  5. package/build/commands/audit.js +7 -4
  6. package/build/commands/audit.js.map +1 -1
  7. package/build/commands/diff.d.ts.map +1 -1
  8. package/build/commands/diff.js +10 -10
  9. package/build/commands/diff.js.map +1 -1
  10. package/build/commands/info.d.ts.map +1 -1
  11. package/build/commands/info.js +16 -14
  12. package/build/commands/info.js.map +1 -1
  13. package/build/commands/init.d.ts.map +1 -1
  14. package/build/commands/init.js +1 -1
  15. package/build/commands/init.js.map +1 -1
  16. package/build/commands/install.d.ts.map +1 -1
  17. package/build/commands/install.js +153 -67
  18. package/build/commands/install.js.map +1 -1
  19. package/build/commands/move.d.ts.map +1 -1
  20. package/build/commands/move.js +5 -4
  21. package/build/commands/move.js.map +1 -1
  22. package/build/commands/outdated.js +1 -1
  23. package/build/commands/outdated.js.map +1 -1
  24. package/build/commands/update.d.ts.map +1 -1
  25. package/build/commands/update.js +14 -7
  26. package/build/commands/update.js.map +1 -1
  27. package/build/commands/why.d.ts.map +1 -1
  28. package/build/commands/why.js +28 -7
  29. package/build/commands/why.js.map +1 -1
  30. package/build/components/DiffView.d.ts +3 -1
  31. package/build/components/DiffView.d.ts.map +1 -1
  32. package/build/components/DiffView.js +2 -2
  33. package/build/components/DiffView.js.map +1 -1
  34. package/build/components/InitSuccess.d.ts.map +1 -1
  35. package/build/components/InitSuccess.js +4 -1
  36. package/build/components/InitSuccess.js.map +1 -1
  37. package/build/components/InstallSummary.d.ts +7 -2
  38. package/build/components/InstallSummary.d.ts.map +1 -1
  39. package/build/components/InstallSummary.js +3 -1
  40. package/build/components/InstallSummary.js.map +1 -1
  41. package/build/hooks/useInitState.d.ts +9 -1
  42. package/build/hooks/useInitState.d.ts.map +1 -1
  43. package/build/hooks/useInitState.js +52 -10
  44. package/build/hooks/useInitState.js.map +1 -1
  45. package/build/hooks/useListActions.d.ts.map +1 -1
  46. package/build/hooks/useListActions.js +9 -2
  47. package/build/hooks/useListActions.js.map +1 -1
  48. package/build/lib/adapter.d.ts +14 -9
  49. package/build/lib/adapter.d.ts.map +1 -1
  50. package/build/lib/adapter.js +46 -8
  51. package/build/lib/adapter.js.map +1 -1
  52. package/build/lib/asset-tools.d.ts +10 -0
  53. package/build/lib/asset-tools.d.ts.map +1 -1
  54. package/build/lib/asset-tools.js +18 -0
  55. package/build/lib/asset-tools.js.map +1 -1
  56. package/build/lib/completion/candidates.d.ts.map +1 -1
  57. package/build/lib/completion/candidates.js +21 -8
  58. package/build/lib/completion/candidates.js.map +1 -1
  59. package/build/lib/config-entries.d.ts +3 -3
  60. package/build/lib/config-entries.d.ts.map +1 -1
  61. package/build/lib/config-entries.js +16 -6
  62. package/build/lib/config-entries.js.map +1 -1
  63. package/build/lib/config-lock.d.ts +2 -1
  64. package/build/lib/config-lock.d.ts.map +1 -1
  65. package/build/lib/config-lock.js +10 -2
  66. package/build/lib/config-lock.js.map +1 -1
  67. package/build/lib/cross-scope.d.ts +6 -2
  68. package/build/lib/cross-scope.d.ts.map +1 -1
  69. package/build/lib/cross-scope.js +20 -13
  70. package/build/lib/cross-scope.js.map +1 -1
  71. package/build/lib/diagnostics.d.ts +3 -2
  72. package/build/lib/diagnostics.d.ts.map +1 -1
  73. package/build/lib/diagnostics.js +6 -4
  74. package/build/lib/diagnostics.js.map +1 -1
  75. package/build/lib/diff-command.d.ts +7 -2
  76. package/build/lib/diff-command.d.ts.map +1 -1
  77. package/build/lib/diff-command.js +14 -10
  78. package/build/lib/diff-command.js.map +1 -1
  79. package/build/lib/gitignore.d.ts +8 -0
  80. package/build/lib/gitignore.d.ts.map +1 -1
  81. package/build/lib/gitignore.js +51 -6
  82. package/build/lib/gitignore.js.map +1 -1
  83. package/build/lib/hook-config.d.ts +90 -7
  84. package/build/lib/hook-config.d.ts.map +1 -1
  85. package/build/lib/hook-config.js +135 -11
  86. package/build/lib/hook-config.js.map +1 -1
  87. package/build/lib/hook-script.d.ts +45 -0
  88. package/build/lib/hook-script.d.ts.map +1 -1
  89. package/build/lib/hook-script.js +118 -1
  90. package/build/lib/hook-script.js.map +1 -1
  91. package/build/lib/init.d.ts +34 -12
  92. package/build/lib/init.d.ts.map +1 -1
  93. package/build/lib/init.js +180 -32
  94. package/build/lib/init.js.map +1 -1
  95. package/build/lib/install-targets.d.ts +35 -8
  96. package/build/lib/install-targets.d.ts.map +1 -1
  97. package/build/lib/install-targets.js +87 -14
  98. package/build/lib/install-targets.js.map +1 -1
  99. package/build/lib/installer.d.ts +18 -2
  100. package/build/lib/installer.d.ts.map +1 -1
  101. package/build/lib/installer.js +215 -38
  102. package/build/lib/installer.js.map +1 -1
  103. package/build/lib/local-edits.d.ts +7 -0
  104. package/build/lib/local-edits.d.ts.map +1 -1
  105. package/build/lib/local-edits.js +21 -2
  106. package/build/lib/local-edits.js.map +1 -1
  107. package/build/lib/mover.d.ts +5 -4
  108. package/build/lib/mover.d.ts.map +1 -1
  109. package/build/lib/mover.js +23 -27
  110. package/build/lib/mover.js.map +1 -1
  111. package/build/lib/multi-tool-install.d.ts +48 -11
  112. package/build/lib/multi-tool-install.d.ts.map +1 -1
  113. package/build/lib/multi-tool-install.js +165 -36
  114. package/build/lib/multi-tool-install.js.map +1 -1
  115. package/build/lib/named-entry.d.ts +12 -0
  116. package/build/lib/named-entry.d.ts.map +1 -1
  117. package/build/lib/named-entry.js +16 -8
  118. package/build/lib/named-entry.js.map +1 -1
  119. package/build/lib/schemas/adapter.d.ts +30 -0
  120. package/build/lib/schemas/adapter.d.ts.map +1 -1
  121. package/build/lib/schemas/adapter.js +27 -5
  122. package/build/lib/schemas/adapter.js.map +1 -1
  123. package/build/lib/sync.d.ts +7 -0
  124. package/build/lib/sync.d.ts.map +1 -1
  125. package/build/lib/sync.js +54 -6
  126. package/build/lib/sync.js.map +1 -1
  127. package/build/lib/touched-paths.d.ts.map +1 -1
  128. package/build/lib/touched-paths.js +2 -1
  129. package/build/lib/touched-paths.js.map +1 -1
  130. package/build/lib/uninstaller.d.ts.map +1 -1
  131. package/build/lib/uninstaller.js +11 -3
  132. package/build/lib/uninstaller.js.map +1 -1
  133. package/build/lib/updater.d.ts +32 -5
  134. package/build/lib/updater.d.ts.map +1 -1
  135. package/build/lib/updater.js +129 -14
  136. package/build/lib/updater.js.map +1 -1
  137. package/package.json +1 -1
  138. package/tool-adapters/claude-code.json +1 -1
  139. package/tool-adapters/codex-cli.json +5 -1
  140. 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 } 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
@@ -142,9 +159,14 @@ export async function executeInstallPlan(plan, options) {
142
159
  // placement for an asset type (e.g. Codex CLI has no `rule` placement) skips
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
- // silent no-op. A hook whose manifest doesn't declare this tool is skipped the same way.
146
- const supportedEntries = placeableEntries(plan, options.adapter);
162
+ // silent no-op. A hook whose manifest doesn't declare this tool is skipped the same way, and so
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).
165
+ const installedBefore = options.installedBefore ?? options.managedFrom ?? lockfile;
166
+ const skipFiles = options.skipUnsupported ? options.files : undefined;
167
+ const supportedEntries = placeableEntries(plan, options.adapter, installedBefore, skipFiles);
147
168
  for (const entry of plan.entries) {
169
+ const entrypoint = skipFiles?.get(planEntryKey(entry))?.entrypoint;
148
170
  if (!getPlacement(options.adapter, entry.asset.type)) {
149
171
  options.onProgress?.(options.scope === 'user'
150
172
  ? `Skipping ${entry.asset.name}: ${options.adapter.displayName} has no user-level ${entry.asset.type}`
@@ -154,8 +176,14 @@ export async function executeInstallPlan(plan, options) {
154
176
  const tools = entry.versionData.tools.join(', ');
155
177
  options.onProgress?.(`Skipping ${entry.asset.name}: the hook is for ${tools} only, not ${options.adapter.tool}`);
156
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
+ }
182
+ else if (!supportedEntries.includes(entry)) {
183
+ options.onProgress?.(`Skipping ${entry.asset.name}: it was uninstalled for ${options.adapter.tool}`);
184
+ }
157
185
  }
158
- if (supportedEntries.length === 0 && plan.entries.length > 0 && !options.skipUnsupported) {
186
+ if (placeableEntries(plan, options.adapter).length === 0 && plan.entries.length > 0 && !options.skipUnsupported) {
159
187
  const undeclared = undeclaredHookError(plan, [options.adapter.tool], options.scope);
160
188
  if (undeclared)
161
189
  throw undeclared;
@@ -165,7 +193,6 @@ export async function executeInstallPlan(plan, options) {
165
193
  throw new InstallerError(`Tool "${options.adapter.tool}" does not support asset type "${plan.entries[0].asset.type}"`, { command: 'atk setup', hint: NO_PROJECT_PLACEMENT_HINT });
166
194
  }
167
195
  // The assets this tool had in place before the plan, by plan entry, which a failure keeps.
168
- const installedBefore = options.installedBefore ?? options.managedFrom ?? lockfile;
169
196
  const inPlace = new Map();
170
197
  for (const entry of supportedEntries) {
171
198
  const installed = findInstalledAsset(installedBefore, entry.asset.name, entry.asset.type, entry.asset.org);
@@ -177,11 +204,16 @@ export async function executeInstallPlan(plan, options) {
177
204
  // The previous copies left in a user config directory the tool no longer reads, removed once the
178
205
  // plan is in place: a failure restores their lockfile entries, which still point at them.
179
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 = [];
180
210
  try {
181
211
  for (const entry of supportedEntries) {
182
212
  created = [];
183
- 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);
184
214
  results.push(result);
215
+ const dropping = `${formatOrgName(entry.asset.org, entry.asset.name)}@${entry.version}`;
216
+ leftovers.push(...leftoverScripts.map((path) => ({ dropping, path })));
185
217
  if (movedCopy)
186
218
  movedCopies.push({ previous: movedCopy, written: result.filesPlaced.map((f) => f.destination) });
187
219
  // A later entry of this plan may land on these files or entries, and must see whose they are.
@@ -274,6 +306,28 @@ export async function executeInstallPlan(plan, options) {
274
306
  `placed that this install replaced — ${errorMessage(error)}`);
275
307
  }
276
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
+ }
277
331
  return results;
278
332
  }
279
333
  /**
@@ -286,6 +340,8 @@ export async function executeInstallPlan(plan, options) {
286
340
  *
287
341
  * `downloaded` is shared by the passes of a multi-tool update or sync, whose plans differ by tool:
288
342
  * an entry it holds is not downloaded again, and the entries this call downloads are added to it.
343
+ * A dependency uninstalled for the tools is downloaded too: its lockfile entry still moves to the
344
+ * plan's version (see {@link recordUninstalledDependencies}).
289
345
  */
290
346
  export async function fetchPlanFiles(plan, adapters, downloaded) {
291
347
  const placeable = new Set(adapters.flatMap((adapter) => placeableEntries(plan, adapter)));
@@ -331,10 +387,30 @@ export function installFailureMessage(error, asset) {
331
387
  }
332
388
  /**
333
389
  * The entries of `plan` the adapter's tool takes, in plan order: those it has a placement for,
334
- * less the hooks whose manifest doesn't declare it (see {@link declarationAllows}).
390
+ * less the hooks whose manifest doesn't declare it (see {@link declarationAllows}). With
391
+ * `installedBefore`, also less the `dependency` entries it records as uninstalled for the tool,
392
+ * which `atk sync` would not place there either; a `direct` entry is placed again. (An update
393
+ * carries the asset's own install reason onto its entry, but skips an asset uninstalled for the
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}).
335
396
  */
336
- export function placeableEntries(plan, adapter) {
337
- return plan.entries.filter(({ asset, versionData }) => getPlacement(adapter, asset.type) && declarationAllows(asset.type, versionData.tools, adapter.tool));
397
+ export function placeableEntries(plan, adapter, installedBefore, files) {
398
+ return plan.entries.filter((entry) => {
399
+ const { asset, reason, versionData } = entry;
400
+ if (!getPlacement(adapter, asset.type) || !declarationAllows(asset.type, versionData.tools, adapter.tool)) {
401
+ return false;
402
+ }
403
+ if (files && !takesEntrypoint(adapter, asset.type, files.get(planEntryKey(entry))?.entrypoint))
404
+ return false;
405
+ if (reason !== 'dependency' || !installedBefore)
406
+ return true;
407
+ const installed = findInstalledAsset(installedBefore, asset.name, asset.type, asset.org);
408
+ return !installed || !isUninstalledForTool(installed, adapter.tool);
409
+ });
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}`;
338
414
  }
339
415
  /**
340
416
  * Undo the installs of `installed` for the adapter's tool, in reverse order (best-effort): delete
@@ -735,9 +811,16 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
735
811
  assetFiles.some((f) => isNodeHookEntrypoint(f.relativePath))) {
736
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.' });
737
813
  }
738
- const placement = placementForEntrypoint(typePlacement, declaredEntrypoint);
814
+ const placement = placementForAsset(typePlacement, declaredEntrypoint, asset.name);
739
815
  // Find the entrypoint file
740
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
+ }
741
824
  // Determine merge content for configMerge mode (a keyed merge; a hook merge doesn't use it)
742
825
  let mergeContent;
743
826
  if (placement.configMerge && !placement.configHookMerge && entrypointFile) {
@@ -776,9 +859,39 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
776
859
  : []),
777
860
  ...staleConfigEntries(previousEntry, declaredEntrypoint, adapter, placement).map((stale) => configEntryPath(stale, previousEntry, adapter, projectDir)),
778
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
+ : [];
779
892
  // A config file the merge below couldn't read fails the install before any file is placed, so a
780
893
  // reinstall's files keep the content its previous entries run.
781
- if (placement.configFile && placement.configKey && !placement.fileless) {
894
+ if (placement.configFile && placement.configKey && !placement.fileless && !misplacedCopy) {
782
895
  await checkConfigReadable(fromRoot(basePath, placement.configFile), configFormat, placement.configHookMerge ? 'the hook' : `"${asset.name}"`);
783
896
  }
784
897
  // Branch on placement type
@@ -855,8 +968,10 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
855
968
  // Default single-file placement
856
969
  const destinations = assetFiles.map((file) => resolveFilePath(placement.path, asset.name, basePath, file.relativePath, asset.type, undefined, declaredEntrypoint));
857
970
  if (!force) {
858
- for (const destPath of destinations)
859
- await checkFileConflict(destPath, managedPaths, asset);
971
+ for (const destPath of destinations) {
972
+ if (destPath !== ownHookFile)
973
+ await checkFileConflict(destPath, managedPaths, asset);
974
+ }
860
975
  }
861
976
  checkRealPaths(destinations, asset.name, adapter, projectDir);
862
977
  for (const [index, file] of assetFiles.entries()) {
@@ -903,7 +1018,13 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
903
1018
  // config file as valid event arrays (e.g. settings.json hooks.Stop[]), with the
904
1019
  // command derived from the installed script path.
905
1020
  const { configFile, configKey } = placement;
906
- 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));
907
1028
  configEntries.push(...hookEntries);
908
1029
  }
909
1030
  else if (placement.configFile && placement.configKey) {
@@ -972,11 +1093,7 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
972
1093
  const installedAsset = {
973
1094
  ...(bundleOrigin ? { bundleOrigin } : {}),
974
1095
  ...(lockfileConfigEntries.length > 0 ? { configEntries: lockfileConfigEntries } : {}),
975
- dependencies: (entry.versionData.dependencies ?? []).map((d) => ({
976
- name: d.name,
977
- type: d.type,
978
- ...(d.version ? { version: d.version } : {}),
979
- })),
1096
+ dependencies: lockfileDependencies(entry.versionData),
980
1097
  ...(entry.versionData.description ? { description: entry.versionData.description } : {}),
981
1098
  ...(declaredEntrypoint ? { entrypoint: declaredEntrypoint } : {}),
982
1099
  ...(exclusions.excludedTools ? { excludedTools: exclusions.excludedTools } : {}),
@@ -994,6 +1111,8 @@ async function installAsset(entry, options, managedPaths, managedEntries, owners
994
1111
  await writeLockfile(projectDir, updatedLockfile);
995
1112
  onProgress?.(`Installed ${asset.name}@${entry.version}`);
996
1113
  return {
1114
+ leftoverScripts: scriptsLeft.filter((path) => !filesPlaced.some((f) => f.destination === path) &&
1115
+ !pathsOwnedByOthers(lockfile, identity, adapter, projectDir).has(path)),
997
1116
  lockfile: updatedLockfile,
998
1117
  ...(movedCopy ? { movedCopy } : {}),
999
1118
  result: {
@@ -1019,6 +1138,14 @@ function isOwner(owners, asset) {
1019
1138
  function isRecord(value) {
1020
1139
  return typeof value === 'object' && value !== null && !Array.isArray(value);
1021
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
+ }
1022
1149
  /**
1023
1150
  * `fn` over `items` in order, at most `limit` at a time, settled in the order of `items`. Once one
1024
1151
  * rejects, no further item starts: those it never started are `undefined`, after every started one.
@@ -1112,16 +1239,18 @@ async function mergeFragmentConfig(configFilePath, configKey, format, projectDir
1112
1239
  * Merge a hook asset's event bindings into a tool config file (e.g. .claude/settings.json).
1113
1240
  *
1114
1241
  * Claude Code stores hooks as `hooks.<Event>: [ { matcher?, hooks: [{ type:'command', command }] } ]`,
1115
- * an ARRAY shared by every hook bound to that event. For each event in `hookConfig`, this appends
1116
- * one matcher-group whose command is the installed script path. ATK's group is identified by that
1117
- * command (no marker is written — the tool validates group shape). Idempotent: an existing group
1118
- * owned by this command is dropped before appending, so repeated install/sync doesn't duplicate.
1119
- * 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.
1120
1250
  */
1121
- async function mergeHookConfig(configFilePath, configKey, format, hookConfig, command, projectDir, onProgress, writeOptions = {}) {
1122
- const events = hookConfig ? Object.keys(hookConfig) : [];
1251
+ async function mergeHookConfig(configFilePath, configKey, format, placement, events, command, powershellCommand, projectDir, onProgress, writeOptions = {}) {
1123
1252
  if (events.length === 0) {
1124
- // 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.
1125
1254
  return [];
1126
1255
  }
1127
1256
  try {
@@ -1135,13 +1264,16 @@ async function mergeHookConfig(configFilePath, configKey, format, hookConfig, co
1135
1264
  await mkdir(dir, { recursive: true });
1136
1265
  }
1137
1266
  }
1267
+ if (placement.configHookFormat === 'copilot' && config['version'] === undefined) {
1268
+ config = { version: 1, ...config };
1269
+ }
1138
1270
  if (!config[configKey] || typeof config[configKey] !== 'object' || Array.isArray(config[configKey])) {
1139
1271
  config[configKey] = {};
1140
1272
  }
1141
1273
  const section = config[configKey];
1142
1274
  const entries = [];
1143
- for (const event of events) {
1144
- const group = buildHookGroup(command, hookConfig[event]);
1275
+ for (const { binding, event } of events) {
1276
+ const group = buildHookEntry(placement, command, binding, powershellCommand);
1145
1277
  const existing = Array.isArray(section[event]) ? section[event] : [];
1146
1278
  // Idempotency: remove any prior group this asset owns before re-appending.
1147
1279
  const next = existing.filter((g) => !hookGroupOwnsCommand(g, command));
@@ -1164,10 +1296,6 @@ async function mergeHookConfig(configFilePath, configKey, format, hookConfig, co
1164
1296
  });
1165
1297
  }
1166
1298
  }
1167
- /** The {@link PlanFiles} key of a plan entry: one asset version. */
1168
- function planEntryKey(entry) {
1169
- return `${entry.asset.type}:${entry.asset.org ?? ''}:${entry.asset.name}@${entry.version}`;
1170
- }
1171
1299
  /**
1172
1300
  * The memory-template block or keyed config entries an asset of `name` and `type` will write: the
1173
1301
  * fragment's own entry names for a fragment merge, the asset name for any other keyed merge. A
@@ -1194,12 +1322,60 @@ function plannedSharedEntries(name, type, placement, basePath, mergeContent) {
1194
1322
  })),
1195
1323
  ];
1196
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. The exclusions, config entries and install reason carry over, and `files` are the
1332
+ * downloaded version's, as placing it for this tool would record them, each with the `installedPath`
1333
+ * the entry had for that file. Returns `lockfile` as written.
1334
+ */
1335
+ async function recordUninstalledDependencies(plan, placed, lockfile, options, skipFiles) {
1336
+ let updated = lockfile;
1337
+ for (const entry of placeableEntries(plan, options.adapter, undefined, skipFiles)) {
1338
+ if (placed.includes(entry))
1339
+ continue;
1340
+ const { asset, version, versionData } = entry;
1341
+ const current = findInstalledAsset(updated, asset.name, asset.type, asset.org);
1342
+ if (!current || current.version === version)
1343
+ continue;
1344
+ const { entrypoint, files } = options.files?.get(planEntryKey(entry)) ?? (await fetchAssetFiles(asset, version, asset.org));
1345
+ const placement = placementForAsset(getPlacement(options.adapter, asset.type), entrypoint, asset.name);
1346
+ const { description: _description, entrypoint: _entrypoint, pinnedVersion: _pinnedVersion, ...kept } = current;
1347
+ // A tool outside the run may still have this copy placed, where its paths say.
1348
+ const installedPaths = new Map(current.files.map((f) => [f.sourcePath, f.installedPath]));
1349
+ updated = addAssetToLockfile(updated, {
1350
+ ...kept,
1351
+ dependencies: lockfileDependencies(versionData),
1352
+ ...(versionData.description ? { description: versionData.description } : {}),
1353
+ ...(entrypoint ? { entrypoint } : {}),
1354
+ files: placement.fileless || asset.type === 'memory-template'
1355
+ ? []
1356
+ : files.map((file) => {
1357
+ const installedPath = installedPaths.get(file.relativePath);
1358
+ return {
1359
+ checksum: hashBytes(file.content),
1360
+ ...(installedPath ? { installedPath } : {}),
1361
+ sourcePath: file.relativePath,
1362
+ };
1363
+ }),
1364
+ version,
1365
+ });
1366
+ options.onProgress?.(`Recorded ${formatOrgName(asset.org, asset.name)}@${version} in the lockfile without placing it: ` +
1367
+ `it was uninstalled for ${options.adapter.tool}`);
1368
+ }
1369
+ if (updated !== lockfile)
1370
+ await writeLockfile(options.projectDir, updated);
1371
+ return updated;
1372
+ }
1197
1373
  /**
1198
1374
  * Remove the config entries `previous` recorded for the adapter's tool that this install has just
1199
1375
  * replaced: those in a file other than the placement's `configFile`, and a hook's groups that run
1200
1376
  * another command than the one just registered ({@link staleHookCommandEntries}). An adapter that
1201
1377
  * moved its config file (copilot-cli's mcp-config, from `copilot/mcp-config.json` to
1202
- * `.vscode/mcp.json`) left them where the tool doesn't read them; a hook placed with project-scope
1378
+ * `.vscode/mcp.json`, then to `.github/mcp.json`) left them where the tool doesn't read them; a hook placed with project-scope
1203
1379
  * rules at the user root left a group the tool would run beside the new one. As with an uninstall,
1204
1380
  * an entry holding the value of another asset that owns it stays, for that asset's own sync to
1205
1381
  * move. A file left empty is deleted. (`atk sync` removes the asset before reinstalling it, so
@@ -1289,7 +1465,8 @@ async function revertConfigEntry(configFilePath, keyPath, command, format, delet
1289
1465
  delete config[sectionKey];
1290
1466
  }
1291
1467
  }
1292
- if (deleteWhenEmpty && Object.keys(config).length === 0) {
1468
+ const empty = command !== undefined ? isEmptyHookConfig(config) : Object.keys(config).length === 0;
1469
+ if (deleteWhenEmpty && empty) {
1293
1470
  await removeEmptiedConfigFile(configFilePath, format, writeOptions);
1294
1471
  return;
1295
1472
  }