claude-dev-env 8.109.3 → 8.109.4

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.
@@ -15,6 +15,7 @@ import {
15
15
  readdirSync,
16
16
  realpathSync,
17
17
  rmSync,
18
+ symlinkSync,
18
19
  writeFileSync,
19
20
  } from 'node:fs';
20
21
  import { tmpdir } from 'node:os';
@@ -41,6 +42,15 @@ const RETIRED_AGENT_FILE_NAMES = ['clean-coder.md', 'code-quality-agent.md', 'pr
41
42
  const PERSONAL_SKILL_NAME = 'my-notes';
42
43
  const REVIEW_PROCEDURE_FILE_NAME = 'high.md';
43
44
 
45
+ function entryExistsWithoutFollowing(entryPath) {
46
+ try {
47
+ lstatSync(entryPath);
48
+ return true;
49
+ } catch {
50
+ return false;
51
+ }
52
+ }
53
+
44
54
  /**
45
55
  * @param {string} homeDirectory
46
56
  * @param {string[]} extraArguments
@@ -166,12 +176,17 @@ test('a full install writes skills and agents under .agents and points .claude a
166
176
  assert.equal(existsSync(canonicalSkillFile), true, 'skill file lives under .agents/skills');
167
177
  assert.equal(existsSync(canonicalEli5SkillFile), true, 'ELI5 skill file lives under .agents/skills');
168
178
  assert.equal(existsSync(canonicalAgentFile), true, 'agent file lives under .agents/agents');
169
- assert.equal(lstatSync(skillsLookupDirectory).isSymbolicLink(), true);
170
- assert.equal(lstatSync(agentsLookupDirectory).isSymbolicLink(), true);
179
+ assert.equal(lstatSync(skillsLookupDirectory).isDirectory(), true);
180
+ assert.equal(lstatSync(skillsLookupDirectory).isSymbolicLink(), false);
181
+ assert.equal(lstatSync(join(skillsLookupDirectory, SHIPPED_SKILL_NAME)).isSymbolicLink(), true);
171
182
  assert.equal(
172
- isDirectoryPointerTo(skillsLookupDirectory, skillsInstallDirectory),
183
+ isDirectoryPointerTo(
184
+ join(skillsLookupDirectory, SHIPPED_SKILL_NAME),
185
+ join(skillsInstallDirectory, SHIPPED_SKILL_NAME),
186
+ ),
173
187
  true,
174
188
  );
189
+ assert.equal(lstatSync(agentsLookupDirectory).isSymbolicLink(), true);
175
190
  assert.equal(
176
191
  isDirectoryPointerTo(agentsLookupDirectory, agentsInstallDirectory),
177
192
  true,
@@ -381,7 +396,7 @@ test('installs omit retired agents in each active agents home', () => {
381
396
  }
382
397
  });
383
398
 
384
- test('a real skills directory from an older install lands in .agents and stays readable through the pointer', () => {
399
+ test('a personal skill folder under .claude stays in the Claude folder and is not copied into .agents', () => {
385
400
  const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-relocate-'));
386
401
  const claudeHome = join(homeDirectory, '.claude');
387
402
  const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
@@ -398,22 +413,23 @@ test('a real skills directory from an older install lands in .agents and stays r
398
413
  homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME,
399
414
  PERSONAL_SKILL_NAME, 'notes.md',
400
415
  );
401
- assert.equal(lstatSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME)).isSymbolicLink(), true);
402
- assert.equal(existsSync(canonicalPersonalFile), true);
416
+ assert.equal(lstatSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME)).isSymbolicLink(), false);
403
417
  assert.equal(
404
- readFileSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md'), 'utf8'),
405
- 'keep this personal skill\n',
418
+ lstatSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME)).isSymbolicLink(),
419
+ false,
420
+ 'the personal skill stays a folder in the Claude folder, not a link',
406
421
  );
422
+ assert.equal(existsSync(canonicalPersonalFile), false, 'the personal skill is not copied into .agents');
407
423
  assert.equal(
408
- realpathSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md')),
409
- realpathSync(canonicalPersonalFile),
424
+ readFileSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md'), 'utf8'),
425
+ 'keep this personal skill\n',
410
426
  );
411
427
  } finally {
412
428
  rmSync(homeDirectory, { recursive: true, force: true });
413
429
  }
414
430
  });
415
431
 
416
- test('uninstall removes managed skill files from the agents home and leaves a personal skill reachable through the pointer', () => {
432
+ test('uninstall removes the shipped skills and keeps a personal skill in the Claude folder', () => {
417
433
  const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-uninstall-'));
418
434
  const claudeHome = join(homeDirectory, '.claude');
419
435
  const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
@@ -435,18 +451,78 @@ test('uninstall removes managed skill files from the agents home and leaves a pe
435
451
  PERSONAL_SKILL_NAME, 'notes.md',
436
452
  );
437
453
  assert.equal(existsSync(shippedSkillFile), false);
438
- assert.equal(existsSync(personalSkillFile), true);
454
+ assert.equal(existsSync(personalSkillFile), false, 'a personal skill never enters .agents');
455
+ assert.equal(
456
+ entryExistsWithoutFollowing(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, SHIPPED_SKILL_NAME)),
457
+ false,
458
+ 'the shipped skill link is removed',
459
+ );
460
+ assert.equal(
461
+ lstatSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME)).isSymbolicLink(),
462
+ false,
463
+ 'the Claude skills folder stays a folder, not a link',
464
+ );
465
+ assert.equal(
466
+ readFileSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md'), 'utf8'),
467
+ 'keep this personal skill\n',
468
+ );
469
+ } finally {
470
+ rmSync(homeDirectory, { recursive: true, force: true });
471
+ }
472
+ });
473
+
474
+ test('an old skills pointer becomes a folder that links each shipped skill', () => {
475
+ const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-migrate-'));
476
+ const claudeHome = join(homeDirectory, '.claude');
477
+ const agentsSkillsDirectory = join(homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME);
478
+ const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
479
+ try {
480
+ runInstaller(homeDirectory, []);
481
+ rmSync(skillsLookupDirectory, { recursive: true, force: true });
482
+ symlinkSync(agentsSkillsDirectory, skillsLookupDirectory, 'dir');
483
+ assert.equal(lstatSync(skillsLookupDirectory).isSymbolicLink(), true);
484
+
485
+ runInstaller(homeDirectory, []);
486
+
487
+ assert.equal(lstatSync(skillsLookupDirectory).isSymbolicLink(), false);
439
488
  assert.equal(
440
489
  isDirectoryPointerTo(
441
- join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME),
442
- join(homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME),
490
+ join(skillsLookupDirectory, SHIPPED_SKILL_NAME),
491
+ join(agentsSkillsDirectory, SHIPPED_SKILL_NAME),
443
492
  ),
444
493
  true,
445
- 'the lookup pointer stays so a personal skill remains discoverable',
446
494
  );
447
495
  assert.equal(
448
- readFileSync(join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME, PERSONAL_SKILL_NAME, 'notes.md'), 'utf8'),
449
- 'keep this personal skill\n',
496
+ readFileSync(join(skillsLookupDirectory, SHIPPED_SKILL_NAME, 'SKILL.md'), 'utf8'),
497
+ readFileSync(join(agentsSkillsDirectory, SHIPPED_SKILL_NAME, 'SKILL.md'), 'utf8'),
498
+ );
499
+ } finally {
500
+ rmSync(homeDirectory, { recursive: true, force: true });
501
+ }
502
+ });
503
+
504
+ test('a link left behind by a retired skill is removed on the next install', () => {
505
+ const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-agents-retired-link-'));
506
+ const claudeHome = join(homeDirectory, '.claude');
507
+ const agentsSkillsDirectory = join(homeDirectory, '.agents', MANAGED_SKILLS_DIRECTORY_NAME);
508
+ const skillsLookupDirectory = join(claudeHome, MANAGED_SKILLS_DIRECTORY_NAME);
509
+ try {
510
+ runInstaller(homeDirectory, []);
511
+ symlinkSync(
512
+ join(agentsSkillsDirectory, 'retired-skill'),
513
+ join(skillsLookupDirectory, 'retired-skill'),
514
+ 'dir',
515
+ );
516
+
517
+ runInstaller(homeDirectory, []);
518
+
519
+ assert.equal(entryExistsWithoutFollowing(join(skillsLookupDirectory, 'retired-skill')), false);
520
+ assert.equal(
521
+ isDirectoryPointerTo(
522
+ join(skillsLookupDirectory, SHIPPED_SKILL_NAME),
523
+ join(agentsSkillsDirectory, SHIPPED_SKILL_NAME),
524
+ ),
525
+ true,
450
526
  );
451
527
  } finally {
452
528
  rmSync(homeDirectory, { recursive: true, force: true });
package/bin/install.mjs CHANGED
@@ -114,7 +114,10 @@ import {
114
114
  } from './resolve-package-managed-directory.mjs';
115
115
  import {
116
116
  ensureDirectoryPointer,
117
+ ensureLinkedSkillFolder,
118
+ isLinkToOtherDirectory,
117
119
  POINTER_ACTION_CREATED,
120
+ readPathKind,
118
121
  } from './publish-directory-pointer.mjs';
119
122
  import {
120
123
  parseInstallTargetSelectionFromArgv,
@@ -193,11 +196,11 @@ export const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'system-prompts
193
196
  /**
194
197
  * Every top-level lookup directory the installer writes into under ~/.claude:
195
198
  * the content directories plus skills, agents, and hooks. Skills and agents
196
- * live under the agents home; `~/.claude/skills` and `~/.claude/agents` are
197
- * directory pointers to that home. The uninstall purge walks this list to find
198
- * the root a recorded file belongs to and to drop a managed directory the purge
199
- * empties, and the full-install stale-file prune walks it to give each root its
200
- * own diff.
199
+ * live under the agents home. `~/.claude/skills` is a folder of links into
200
+ * it, and `~/.claude/agents` is a directory pointer to that home. The uninstall
201
+ * purge walks this list to find the root a recorded file belongs to and to drop
202
+ * a managed directory the purge empties, and the full-install stale-file prune
203
+ * walks it to give each root its own diff.
201
204
  */
202
205
  export const MANAGED_TOP_LEVEL_DIRECTORY_NAMES = [
203
206
  ...CONTENT_DIRECTORIES,
@@ -934,9 +937,10 @@ function owningManagedRoot(installedFilePath) {
934
937
  /**
935
938
  * Publish harness lookup paths as directory pointers to the agents home.
936
939
  *
937
- * Skills and agents live under `~/.agents` (or the per-root agents home).
938
- * Claude Code discovers them at the lookup paths under the managed Claude root,
939
- * so those two paths are pointers. A real directory from an older install at a
940
+ * Agents, hooks, and scripts live under `~/.agents` (or the per-root agents
941
+ * home). Claude Code discovers them at the lookup paths under the managed Claude
942
+ * root, so those paths are pointers. The skills lookup is a folder of links
943
+ * instead; see ensureLinkedSkillFolder. A directory from an older install at a
940
944
  * lookup path is merged into the agents home before the pointer is written.
941
945
  *
942
946
  * A pointer that already aimed at its target is left out of the result, so a
@@ -947,10 +951,6 @@ function owningManagedRoot(installedFilePath) {
947
951
  */
948
952
  function publishManagedLookupPointers() {
949
953
  const pointerPairs = [
950
- [
951
- INSTALL_ROOT_RESOLUTION.skillsLookupDirectory,
952
- INSTALL_ROOT_RESOLUTION.skillsInstallDirectory,
953
- ],
954
954
  [
955
955
  INSTALL_ROOT_RESOLUTION.agentsLookupDirectory,
956
956
  INSTALL_ROOT_RESOLUTION.agentsInstallDirectory,
@@ -2530,39 +2530,53 @@ function manifestFilesWithFailedPrunes(installedFiles, failedPrunePaths) {
2530
2530
  * @returns {number} How many retired skill directories reached the backup root.
2531
2531
  */
2532
2532
  function pruneRetiredSkills(installedSkillNames, priorManifestSkills) {
2533
- const skillsDirectory = join(CLAUDE_HOME, MANAGED_SKILLS_DIRECTORY_NAME);
2534
- if (!existsSync(skillsDirectory)) return 0;
2533
+ const skillsRoots = [
2534
+ { directory: join(AGENTS_HOME, MANAGED_SKILLS_DIRECTORY_NAME), home: AGENTS_HOME },
2535
+ { directory: join(CLAUDE_HOME, MANAGED_SKILLS_DIRECTORY_NAME), home: CLAUDE_HOME },
2536
+ ];
2535
2537
  const retiredSkillNames = new Set(
2536
2538
  [...EVER_SHIPPED_SKILL_NAMES].filter(skillName => !installedSkillNames.has(skillName))
2537
2539
  );
2538
2540
  const priorSkillNames = new Set(priorManifestSkills || []);
2539
2541
  const backupRoot = currentRunBackupRoot();
2540
- const existingSkillDirs = readdirSync(skillsDirectory, { withFileTypes: true })
2541
- .filter(entry => entry.isDirectory());
2542
2542
  let movedDirectoryCount = 0;
2543
- for (const skillDir of existingSkillDirs) {
2544
- const skillName = skillDir.name;
2545
- if (NEVER_PRUNED_SKILL_DIRECTORIES.has(skillName)) continue;
2546
- if (installedSkillNames.has(skillName)) continue;
2547
- const isPruneCandidate = priorSkillNames.has(skillName) || retiredSkillNames.has(skillName);
2548
- if (!isPruneCandidate) continue;
2549
- const didMove = moveIntoRunBackup(
2550
- join(skillsDirectory, skillName),
2551
- backupRoot,
2552
- join(MANAGED_SKILLS_DIRECTORY_NAME, skillName),
2553
- RETIRED_SKILL_REASON_LABEL,
2554
- CLAUDE_HOME,
2555
- );
2556
- if (didMove) movedDirectoryCount++;
2543
+ for (const eachRoot of skillsRoots) {
2544
+ if (lstatSync(eachRoot.directory, { throwIfNoEntry: false })?.isDirectory() !== true) continue;
2545
+ const existingSkillDirs = readdirSync(eachRoot.directory, { withFileTypes: true })
2546
+ .filter(entry => entry.isDirectory());
2547
+ for (const skillDir of existingSkillDirs) {
2548
+ const skillName = skillDir.name;
2549
+ if (NEVER_PRUNED_SKILL_DIRECTORIES.has(skillName)) continue;
2550
+ if (installedSkillNames.has(skillName)) continue;
2551
+ const isPruneCandidate = priorSkillNames.has(skillName) || retiredSkillNames.has(skillName);
2552
+ if (!isPruneCandidate) continue;
2553
+ const didMove = moveIntoRunBackup(
2554
+ join(eachRoot.directory, skillName),
2555
+ backupRoot,
2556
+ join(MANAGED_SKILLS_DIRECTORY_NAME, skillName),
2557
+ RETIRED_SKILL_REASON_LABEL,
2558
+ eachRoot.home,
2559
+ );
2560
+ if (didMove) movedDirectoryCount++;
2561
+ }
2557
2562
  }
2558
2563
  return movedDirectoryCount;
2559
2564
  }
2560
2565
 
2566
+ function isRecordThroughLink(filePath, lookupRoot) {
2567
+ const firstSegment = relative(lookupRoot, resolve(filePath)).split(sep)[0];
2568
+ if (firstSegment === '' || firstSegment === '..') return false;
2569
+ return readPathKind(join(lookupRoot, firstSegment)) === 'symlink';
2570
+ }
2571
+
2561
2572
  function pruneStaleFilesAcrossManagedRoots(priorInstalledFiles, currentInstalledFiles, backupRoot) {
2562
2573
  let prunedCount = 0;
2563
2574
  let skillsPrunedCount = 0;
2564
2575
  const failedPaths = [];
2565
- for (const rootName of MANAGED_TOP_LEVEL_DIRECTORY_NAMES) {
2576
+ const lookupRootNames = MANAGED_TOP_LEVEL_DIRECTORY_NAMES.filter(
2577
+ rootName => rootName !== MANAGED_SKILLS_DIRECTORY_NAME,
2578
+ );
2579
+ for (const rootName of lookupRootNames) {
2566
2580
  const rootOutcome = pruneStaleInstalledFiles(
2567
2581
  priorInstalledFiles,
2568
2582
  currentInstalledFiles,
@@ -2571,23 +2585,43 @@ function pruneStaleFilesAcrossManagedRoots(priorInstalledFiles, currentInstalled
2571
2585
  );
2572
2586
  prunedCount += rootOutcome.prunedCount;
2573
2587
  failedPaths.push(...rootOutcome.failedPaths);
2574
- if (rootName === MANAGED_SKILLS_DIRECTORY_NAME) {
2575
- skillsPrunedCount = rootOutcome.prunedCount;
2576
- }
2588
+ }
2589
+ const skillsLookupRoot = join(CLAUDE_HOME, MANAGED_SKILLS_DIRECTORY_NAME);
2590
+ const skillsCanonicalRoot = join(AGENTS_HOME, MANAGED_SKILLS_DIRECTORY_NAME);
2591
+ if (lstatSync(skillsLookupRoot, { throwIfNoEntry: false })?.isDirectory() === true) {
2592
+ const skillsLookupOutcome = pruneStaleInstalledFiles(
2593
+ priorInstalledFiles?.filter(filePath => !isRecordThroughLink(filePath, skillsLookupRoot)) ?? null,
2594
+ currentInstalledFiles.map(filePath => isInsideDirectory(filePath, skillsCanonicalRoot)
2595
+ ? join(skillsLookupRoot, relative(skillsCanonicalRoot, filePath))
2596
+ : filePath),
2597
+ skillsLookupRoot,
2598
+ join(backupRoot, MANAGED_SKILLS_DIRECTORY_NAME),
2599
+ );
2600
+ prunedCount += skillsLookupOutcome.prunedCount;
2601
+ failedPaths.push(...skillsLookupOutcome.failedPaths);
2602
+ skillsPrunedCount = skillsLookupOutcome.prunedCount;
2577
2603
  }
2578
2604
  for (const rootName of [MANAGED_AGENTS_DIRECTORY_NAME, MANAGED_SKILLS_DIRECTORY_NAME]) {
2579
2605
  const lookupRoot = join(CLAUDE_HOME, rootName);
2580
2606
  const canonicalRoot = join(AGENTS_HOME, rootName);
2581
- const canonicalCurrentFiles = currentInstalledFiles.map(filePath =>
2582
- isInsideDirectory(filePath, lookupRoot)
2583
- ? join(canonicalRoot, relative(lookupRoot, filePath))
2584
- : filePath,
2585
- );
2607
+ const toCanonicalPath = filePath => isInsideDirectory(filePath, lookupRoot)
2608
+ ? join(canonicalRoot, relative(lookupRoot, filePath))
2609
+ : filePath;
2610
+ const canonicalCurrentFiles = currentInstalledFiles.map(toCanonicalPath);
2611
+ const canonicalPriorFiles = priorInstalledFiles === null
2612
+ ? null
2613
+ : priorInstalledFiles
2614
+ .filter(filePath => !(rootName === MANAGED_SKILLS_DIRECTORY_NAME
2615
+ && dirname(resolve(filePath)) === resolve(lookupRoot)))
2616
+ .map(toCanonicalPath);
2617
+ const canonicalBackupRoot = rootName === MANAGED_SKILLS_DIRECTORY_NAME
2618
+ ? join(backupRoot, rootName)
2619
+ : join(backupRoot, 'agents-home', rootName);
2586
2620
  const rootOutcome = pruneStaleInstalledFiles(
2587
- priorInstalledFiles,
2621
+ canonicalPriorFiles,
2588
2622
  canonicalCurrentFiles,
2589
2623
  canonicalRoot,
2590
- join(backupRoot, 'agents-home', rootName),
2624
+ canonicalBackupRoot,
2591
2625
  { managedHomeDirectory: AGENTS_HOME },
2592
2626
  );
2593
2627
  prunedCount += rootOutcome.prunedCount;
@@ -2659,7 +2693,7 @@ function pruneRetiredHookRegistrations(settingsPath, retiredHookPaths) {
2659
2693
  * read before the run mutated settings. The caller records each stand-in in
2660
2694
  * the manifest so a later install removes it once no registration names it.
2661
2695
  *
2662
- * @param {Set<string>} copiedSkillNames Skill directory names this run wrote.
2696
+ * @param {Set<string>} copiedSkillNames Skill directory names this run wrote or left in place as a user link.
2663
2697
  * @param {string[]|null} priorManifestSkills The prior manifest's skill names, or null.
2664
2698
  * @param {string[]|null} priorManifestFiles The prior manifest's file list, or null.
2665
2699
  * @param {string[]} installedFiles Every file this run copied.
@@ -3031,9 +3065,13 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
3031
3065
  for (const skillDir of skillDirs) {
3032
3066
  if (allowedSkills && !allowedSkills.has(skillDir.name)) continue;
3033
3067
  const skillSourceDirectory = join(skillsSource, skillDir.name);
3034
- const skillDestinationDirectory = join(CLAUDE_HOME, MANAGED_SKILLS_DIRECTORY_NAME, skillDir.name);
3035
- if (lstatSync(skillDestinationDirectory, { throwIfNoEntry: false })?.isSymbolicLink()) {
3068
+ const skillDestinationDirectory = join(INSTALL_ROOT_RESOLUTION.skillsInstallDirectory, skillDir.name);
3069
+ const skillLookupPath = join(INSTALL_ROOT_RESOLUTION.skillsLookupDirectory, skillDir.name);
3070
+ const destinationIsLink = lstatSync(skillDestinationDirectory, { throwIfNoEntry: false })?.isSymbolicLink();
3071
+ if (isLinkToOtherDirectory(skillLookupPath, skillDestinationDirectory) || destinationIsLink) {
3036
3072
  console.log(` = ${join(MANAGED_SKILLS_DIRECTORY_NAME, skillDir.name)} (linked skill left in place)`);
3073
+ copiedSkillNames.add(skillDir.name);
3074
+ if (!destinationIsLink) allInstalledFiles.push(...collectFiles(skillDestinationDirectory));
3037
3075
  continue;
3038
3076
  }
3039
3077
  const stats = copyTree(skillSourceDirectory, skillDestinationDirectory);
@@ -3370,10 +3408,16 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
3370
3408
  );
3371
3409
  }
3372
3410
  }
3411
+ const skillLinks = ensureLinkedSkillFolder(
3412
+ INSTALL_ROOT_RESOLUTION.skillsLookupDirectory,
3413
+ INSTALL_ROOT_RESOLUTION.skillsInstallDirectory,
3414
+ join(currentRunBackupRoot(), MANAGED_SKILLS_DIRECTORY_NAME),
3415
+ );
3416
+ allInstalledFiles.push(...skillLinks.createdLinkPaths);
3373
3417
  const manifestSkillNames = didPruneFinish
3374
3418
  ? [...installedSkillNames].sort()
3375
3419
  : unionOfSkillNames(priorManifestSkills || [], [...installedSkillNames]).sort();
3376
- const allManagedInstalledFiles = allInstalledFiles.filter(
3420
+ const allManagedInstalledFiles = [...new Set([...allInstalledFiles, ...skillLinks.linkPaths])].filter(
3377
3421
  eachPath => !allUserOwnedPreferencePaths.has(eachPath),
3378
3422
  );
3379
3423
  const manifestFiles = didPruneFinish
@@ -3742,7 +3786,7 @@ Examples:
3742
3786
  npx ${PACKAGE_NAME} --profiles editor,mel --only core
3743
3787
 
3744
3788
  Install location: ~/.claude/ by default; CLAUDE_CONFIG_DIR or --target selects another managed root.
3745
- Skills and agents live under ~/.agents (sibling of ~/.claude). ~/.claude/skills and ~/.claude/agents are directory pointers to that home.
3789
+ Skills and agents live under ~/.agents (sibling of ~/.claude). ~/.claude/agents is a directory pointer to that home, and ~/.claude/skills is a folder of links to the skills there.
3746
3790
  Named profiles resolve under LLM_SETTINGS_PROFILES_ROOT or ~/.claude-profiles/<directoryName>.
3747
3791
  Codex exec-policy files copy into ~/.codex/rules, or CODEX_HOME/rules when CODEX_HOME is set.
3748
3792
  A reinstall moves the Cursor rule files older installs generated under ~/.cursor/rules into the run backup.
@@ -166,6 +166,23 @@ function prunedSkillBackupContains(claudeDirectory, skillsRelativePath) {
166
166
  return prunedBackupContains(claudeDirectory, join(SKILLS_DIRECTORY_NAME, skillsRelativePath));
167
167
  }
168
168
 
169
+ /**
170
+ * Read every copy of a skill path that a timestamped backup under the skills root holds.
171
+ *
172
+ * @param {string} claudeDirectory The sandbox ~/.claude directory.
173
+ * @param {string} skillsRelativePath The path to read, relative to ~/.claude/skills.
174
+ * @returns {string[]} The text of each backed-up copy.
175
+ */
176
+ function prunedSkillBackupTexts(claudeDirectory, skillsRelativePath) {
177
+ const backupRoot = join(claudeDirectory, PRUNED_BACKUP_DIRECTORY_NAME);
178
+ if (!existsSync(backupRoot)) return [];
179
+ return readdirSync(backupRoot, { withFileTypes: true })
180
+ .filter(entry => entry.isDirectory())
181
+ .map(timestampDir => join(backupRoot, timestampDir.name, SKILLS_DIRECTORY_NAME, skillsRelativePath))
182
+ .filter(backedUpPath => existsSync(backedUpPath))
183
+ .map(backedUpPath => readFileSync(backedUpPath, 'utf8'));
184
+ }
185
+
169
186
  /**
170
187
  * Create an isolated ~/.claude sandbox and return the paths a prune test reads.
171
188
  *
@@ -446,10 +463,14 @@ test('a stale file whose move fails stays on the manifest record for the next ru
446
463
 
447
464
  assert.equal(existsSync(staleFilePath), true, 'the failed move leaves the file in the skill');
448
465
  const recordedFiles = readManifest(sandbox.manifestPath).files;
466
+ const canonicalStaleFilePath = join(
467
+ sandbox.homeDirectory, '.agents', SKILLS_DIRECTORY_NAME,
468
+ SHIPPED_SKILL_DIRECTORY, ...STALE_SKILL_FILE_RELATIVE_SEGMENTS,
469
+ );
449
470
  assert.equal(
450
- recordedFiles.filter(recordedPath => recordedPath === staleFilePath).length,
471
+ recordedFiles.filter(recordedPath => recordedPath === canonicalStaleFilePath).length,
451
472
  1,
452
- 'the fresh manifest carries the failed path exactly once',
473
+ 'the fresh manifest carries the failed agents-home path exactly once',
453
474
  );
454
475
  } finally {
455
476
  rmSync(sandbox.homeDirectory, { recursive: true, force: true });
@@ -837,6 +858,7 @@ test('a full reinstall leaves a skill folder linked into another repository unto
837
858
  try {
838
859
  runInstaller(sandbox.homeDirectory, []);
839
860
  const linkedSkillName = 'efficient-review';
861
+ const shippedSkillText = readFileSync(join(sandbox.homeDirectory, '.agents', 'skills', linkedSkillName, 'SKILL.md'), 'utf8');
840
862
  const repositorySkillDirectory = join(linkedRepositoryDirectory, 'skills', linkedSkillName);
841
863
  const repositorySkillText = 'name: efficient-review\nthe repository copy\n';
842
864
  writeFileWithParents(join(repositorySkillDirectory, 'SKILL.md'), repositorySkillText);
@@ -846,6 +868,7 @@ test('a full reinstall leaves a skill folder linked into another repository unto
846
868
 
847
869
  const installerOutput = runInstallerReadingBothStreams(sandbox.homeDirectory, []);
848
870
 
871
+ assert.match(installerOutput, /skills[\\/]efficient-review \(linked skill left in place\)/);
849
872
  assert.equal(lstatSync(skillLinkPath).isSymbolicLink(), true, 'the skill link stays a link');
850
873
  assert.equal(
851
874
  readFileSync(join(repositorySkillDirectory, 'SKILL.md'), 'utf8'),
@@ -858,15 +881,29 @@ test('a full reinstall leaves a skill folder linked into another repository unto
858
881
  'the install writes no package file into the linked repository',
859
882
  );
860
883
  assert.equal(
861
- prunedSkillBackupContains(sandbox.claudeDirectory, join(linkedSkillName, 'SKILL.md')),
884
+ prunedSkillBackupTexts(sandbox.claudeDirectory, join(linkedSkillName, 'SKILL.md')).includes(repositorySkillText),
862
885
  false,
863
- 'the stale prune moves no file out of the linked repository',
886
+ 'the linked repository copy never reaches the backup',
887
+ );
888
+ assert.equal(
889
+ readFileSync(join(sandbox.homeDirectory, '.agents', 'skills', linkedSkillName, 'SKILL.md'), 'utf8'),
890
+ shippedSkillText,
891
+ 'the shipped copy stays in the agents home for Codex',
892
+ );
893
+ assert.equal(
894
+ prunedSkillBackupTexts(sandbox.claudeDirectory, join(linkedSkillName, 'SKILL.md')).includes(shippedSkillText),
895
+ false,
896
+ 'the shipped copy is not moved to the backup',
864
897
  );
865
- assert.match(installerOutput, /skills[\\/]efficient-review \(linked skill left in place\)/);
866
898
  assert.equal(
867
- readManifest(sandbox.manifestPath).files.some(recordedPath => recordedPath.includes(linkedSkillName)),
899
+ readManifest(sandbox.manifestPath).files.some(recordedPath => recordedPath.includes(join('.claude', 'skills', linkedSkillName))),
868
900
  false,
869
- 'the manifest records no file under the linked skill',
901
+ 'the manifest records no file under the linked skill link',
902
+ );
903
+ assert.equal(
904
+ readManifest(sandbox.manifestPath).files.some(recordedPath => recordedPath.includes(join('.agents', 'skills', linkedSkillName))),
905
+ true,
906
+ 'the manifest keeps the shipped copy so an uninstall removes it',
870
907
  );
871
908
  } finally {
872
909
  rmSync(sandbox.homeDirectory, { recursive: true, force: true });
@@ -3036,7 +3036,7 @@ test('pruneRetiredHookEntriesFromSettings warns and returns 0 when the host conf
3036
3036
  const PSTACK_TEST_PACKAGE_ROOT = dirname(fileURLToPath(new URL('./install.mjs', import.meta.url)));
3037
3037
  const PSTACK_TEST_INSTALLER_PATH = fileURLToPath(new URL('./install.mjs', import.meta.url));
3038
3038
 
3039
- test('a failed update preserves an existing skills lookup pointer', () => {
3039
+ test('a failed update preserves an existing skills lookup folder of links', () => {
3040
3040
  const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-install-pointer-'));
3041
3041
  try {
3042
3042
  writeFileSync(join(homeDirectory, '.gitconfig'), '');
@@ -3060,16 +3060,23 @@ test('a failed update preserves an existing skills lookup pointer', () => {
3060
3060
  env: environment,
3061
3061
  });
3062
3062
  assert.equal(firstRun.status, 0, firstRun.stdout + firstRun.stderr);
3063
- const pointerPath = join(homeDirectory, '.claude', 'skills');
3064
- const targetPath = readlinkSync(pointerPath);
3063
+ const skillsLookupPath = join(homeDirectory, '.claude', 'skills');
3064
+ const skillLinkTargets = new Map(
3065
+ readdirSync(skillsLookupPath)
3066
+ .filter(eachName => lstatSync(join(skillsLookupPath, eachName)).isSymbolicLink())
3067
+ .map(eachName => [eachName, readlinkSync(join(skillsLookupPath, eachName))]),
3068
+ );
3069
+ assert.ok(skillLinkTargets.size > 0);
3065
3070
 
3066
3071
  const failedRun = spawnSync(process.execPath, argumentsForCoreInstall, {
3067
3072
  encoding: 'utf8',
3068
3073
  env: { ...environment, [INSTALL_FAULT_ENV]: FAULT_PHASES.AFTER_FILE_STAGING },
3069
3074
  });
3070
3075
  assert.notEqual(failedRun.status, 0, failedRun.stdout + failedRun.stderr);
3071
- assert.equal(lstatSync(pointerPath).isSymbolicLink(), true);
3072
- assert.equal(readlinkSync(pointerPath), targetPath);
3076
+ assert.equal(lstatSync(skillsLookupPath).isDirectory(), true);
3077
+ for (const [eachName, eachTarget] of skillLinkTargets) {
3078
+ assert.equal(readlinkSync(join(skillsLookupPath, eachName)), eachTarget);
3079
+ }
3073
3080
  } finally {
3074
3081
  rmSync(homeDirectory, { recursive: true, force: true });
3075
3082
  }
@@ -560,7 +560,7 @@ test('installer fault keeps the lookup pointers a prior install published', () =
560
560
  });
561
561
  assert.equal(okRun.status, 0, okRun.stdout + okRun.stderr);
562
562
  const allPointerTargets = [
563
- ...['skills', 'agents', 'hooks', 'scripts'].map((name) => ({
563
+ ...['agents', 'hooks', 'scripts'].map((name) => ({
564
564
  pointerPath: join(homeDirectory, '.claude', name),
565
565
  targetPath: realpathSync(join(homeDirectory, '.agents', name)),
566
566
  })),
@@ -585,6 +585,11 @@ test('installer fault keeps the lookup pointers a prior install published', () =
585
585
  );
586
586
  assert.equal(realpathSync(pointerPath), targetPath);
587
587
  }
588
+ assert.equal(
589
+ lstatSync(join(homeDirectory, '.claude', 'skills')).isDirectory(),
590
+ true,
591
+ `the skills folder survives a fault at ${faultPhase}`,
592
+ );
588
593
  }
589
594
  } finally {
590
595
  rmSync(homeDirectory, { recursive: true, force: true });