Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Share the sibling symlink re-point loop (PRD-7687) (#3113)

tim-inkeep6426bf5722ce
diff --git a/packages/server/src/skill-projection.test.ts b/packages/server/src/skill-projection.test.ts
index c8db506e0..bfd6e4a21 100644
--- a/packages/server/src/skill-projection.test.ts
+++ b/packages/server/src/skill-projection.test.ts
@@ -6,12 +6,13 @@ import {
mkdtempSync,
readFileSync,
readlinkSync,
+ realpathSync,
rmSync,
symlinkSync,
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
import { parseSkillDir } from '@inkeep/open-knowledge-core/skills-catalog';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import {
@@ -19,6 +20,7 @@ import {
projectInPlaceSkill,
projectSkill,
readSkillBundledFiles,
+ relocateInPlaceCanonical,
removeInPlaceSkillCopies,
reverseProjectSkill,
skillHostDir,
@@ -396,4 +398,84 @@ describe('projectInPlaceSkill / removeInPlaceSkillCopies (in-place fan-out guard
expect(existsSync(copy)).toBe(false);
expect(existsSync(join(root, '.opencode/skills/foo'))).toBe(false);
});
+
+ // The re-point sweep after a removal walks EVERY host, not just `targets`,
+ // so it decides the fate of links it was never asked about. Dangling ones are
+ // adopted back onto the canonical; ones still aimed at something real were
+ // aimed there on purpose. Relocation claims a wider set, and this pins the
+ // narrower one so sharing the loop between them cannot quietly widen it.
+ test('remove re-points a DANGLING sibling but leaves one aimed elsewhere alone', () => {
+ const canonical = makeAt('.claude/skills/foo', '# Canonical');
+ // The occurrence actually being removed (a link, so removal is lossless).
+ mkdirSync(join(root, '.cursor/skills'), { recursive: true });
+ symlinkSync(canonical, join(root, '.cursor/skills/foo'), 'dir');
+ // A sibling deliberately aimed at an unrelated bundle, NOT in `targets`.
+ const unrelated = makeAt('vendor/other', '# Someone else');
+ mkdirSync(join(root, '.codex/skills'), { recursive: true });
+ symlinkSync(unrelated, join(root, '.codex/skills/foo'), 'dir');
+ // A sibling pointing at nothing, NOT in `targets`.
+ mkdirSync(join(root, '.opencode/skills'), { recursive: true });
+ symlinkSync(join(root, 'gone'), join(root, '.opencode/skills/foo'), 'dir');
+
+ const removed = removeInPlaceSkillCopies({
+ canonicalAbs: canonical,
+ canonicalHash: hashOf(canonical),
+ name: 'foo',
+ cwd: root,
+ targets: ['cursor'],
+ });
+
+ expect(removed).toEqual(['cursor']);
+ expect(realpathSync(join(root, '.opencode/skills/foo'))).toBe(realpathSync(canonical));
+ expect(realpathSync(join(root, '.codex/skills/foo'))).toBe(realpathSync(unrelated));
+ });
+
+ // The symmetric half of the test above, and it has to use `leaveLinkBehind`
+ // to bite at all. Without it relocation RENAMES the old source away, so a
+ // sibling aimed there simply dangles and the unconditional dangling rule
+ // already claims it — `alsoClaim` changes nothing and a test written that way
+ // passes with `alsoClaim: []`. The claim only does work when the old source
+ // still RESOLVES: the leave-behind link makes the sibling chain through it to
+ // `dest`, which is live, so only `alsoClaim` collapses that chain.
+ //
+ // Asserted on the link's DIRECT target, since `realpathSync` follows the chain
+ // and reports the same answer either way.
+ test('relocate collapses a sibling chained through the leave-behind link', () => {
+ const canonical = makeAt('.agents/skills/foo', '# Canonical');
+ // Aimed at the old source, which survives as a link to `dest`.
+ mkdirSync(join(root, '.cursor/skills'), { recursive: true });
+ symlinkSync(canonical, join(root, '.cursor/skills/foo'), 'dir');
+ // Aimed at an unrelated bundle: nobody asked about it, leave it be.
+ const unrelated = makeAt('vendor/other', '# Someone else');
+ mkdirSync(join(root, '.codex/skills'), { recursive: true });
+ symlinkSync(unrelated, join(root, '.codex/skills/foo'), 'dir');
+
+ // `cwd` must be the REAL root. `mkdtemp` hands back `/var/...` on macOS while
+ // the primitive realpaths its canonical to `/private/var/...`, and the claim
+ // set compares those two spellings of one path — so under a raw tmpdir root
+ // the chain claim silently never matches and this test cannot see it.
+ const realRoot = realpathSync(root);
+ const moved = relocateInPlaceCanonical({
+ canonicalAbs: canonical,
+ canonicalHash: hashOf(canonical),
+ name: 'foo',
+ cwd: realRoot,
+ newTarget: 'claude',
+ leaveLinkBehind: true,
+ });
+
+ expect(moved.ok).toBe(true);
+ const dest = join(realRoot, '.claude/skills/foo');
+ expect(lstatSync(dest).isSymbolicLink()).toBe(false);
+ // The swap: the old source is now a link standing in for the moved folder.
+ expect(lstatSync(canonical).isSymbolicLink()).toBe(true);
+
+ // The claim under test: re-pointed DIRECTLY at dest, not left chained
+ // through the old source. Zero `alsoClaim` and this reads as `canonical`.
+ const cursorLink = join(realRoot, '.cursor/skills/foo');
+ expect(resolve(dirname(cursorLink), readlinkSync(cursorLink))).toBe(dest);
+
+ // Aimed elsewhere on purpose: untouched, so the claim did not widen.
+ expect(realpathSync(join(root, '.codex/skills/foo'))).toBe(realpathSync(unrelated));
+ });
});
diff --git a/packages/server/src/skill-projection.ts b/packages/server/src/skill-projection.ts
index f247e7e64..692ea5ab7 100644
--- a/packages/server/src/skill-projection.ts
+++ b/packages/server/src/skill-projection.ts
@@ -592,10 +592,75 @@ export function relocateInPlaceCanonical(opts: {
if (opts.leaveLinkBehind === true && !existsSync(canonicalAbs)) {
tracedSymlinkSync(skillLinkTarget(cwd, dirname(canonicalAbs), dest), canonicalAbs, 'dir');
}
- // Re-point sibling links that referenced the old source (now gone/dangling).
+ // Claim links that referenced the old source (now gone), plus any resolving
+ // to the new dest THROUGH another link (chain) — links always point DIRECTLY
+ // at the real dir, so removing any one link can never strand another.
+ repointSiblingLinks({
+ name,
+ cwd,
+ roots,
+ target: dest,
+ skip: [dest, canonicalAbs],
+ alsoClaim: [canonicalAbs, dest],
+ });
+ return { ok: true, newAbs: dest };
+}
+
+/** Every install-target host (editors with a project dir + the .agents hub). */
+const ALL_TARGET_HOSTS: readonly SkillHostId[] = [
+ 'agents',
+ ...(PROJECT_SKILL_EDITOR_IDS as readonly EditorId[]),
+];
+
+/**
+ * Re-point sibling symlinks at `target`: walk every install-target host, skip
+ * anything that is not a symlink, and replace each CLAIMED link with one aimed
+ * directly at `target`. Shared by relocation and removal, which walk the same
+ * slots for the same reason.
+ *
+ * A THIRD sweep of this shape lives in `api-extension.ts`, in the promote path.
+ * It is not shared because it walks the placement LEDGER rather than host slots,
+ * so folding it in needs a slot-source parameter this helper does not have. It
+ * also claims a narrower set: dangling or the old source, but not a link chained
+ * through the new dest, which this one claims via `alsoClaim`. Both sweeps fire
+ * on the same relocation, and the divergence is inert because a link resolving
+ * to `dest` already resolves to a real dir. Widen either and they must agree.
+ *
+ * They differ in which links they claim, and that difference is data, not an
+ * inverted condition. A dangling link is ALWAYS claimed: it resolves to
+ * nothing, so re-pointing it cannot lose anything. `alsoClaim` adds link
+ * realpaths that are stale for a caller-specific reason — relocation names the
+ * old source and the new dest, removal names none. Expressing that as a set of
+ * paths, rather than a boolean either caller could invert, is what keeps
+ * removal from re-pointing links that were aimed elsewhere on purpose.
+ *
+ * `skip` is the second difference, and it is not cosmetic. Relocation has
+ * already put two slots in their final form before the sweep runs: the new
+ * `dest`, and the leave-behind link at the old source. Both are in `skip` so the
+ * sweep never removes and rebuilds a link relocation just wrote. Without it the
+ * leave-behind link realpaths to `dest`, which `alsoClaim` covers, so it would
+ * be deleted and recreated with identical bytes. The resulting tree is the same
+ * either way, which is why a tree-comparing test cannot see the difference; the
+ * sequence of filesystem operations is not, and in this file an unnecessary
+ * unlink of a link standing in for a real directory is the scar being avoided.
+ */
+function repointSiblingLinks(opts: {
+ name: string;
+ cwd: string;
+ roots: SkillProjectionRoots;
+ /** Real bundle dir every claimed link is re-pointed at. */
+ target: string;
+ /** Sibling SLOTS never touched, matched on the slot path itself. */
+ skip?: readonly string[];
+ /** Link REALPATHS claimed on top of dangling ones. */
+ alsoClaim?: readonly string[];
+}): void {
+ const { name, cwd, roots, target } = opts;
+ const skip = new Set((opts.skip ?? []).map((p) => resolve(p)));
+ const claim = new Set((opts.alsoClaim ?? []).map((p) => resolve(p)));
for (const host of ALL_TARGET_HOSTS) {
const sib = skillTargetDir(cwd, host, name, roots);
- if (sib === null || resolve(sib) === resolve(dest) || resolve(sib) === canonicalAbs) continue;
+ if (sib === null || skip.has(resolve(sib))) continue;
try {
if (!lstatSync(sib).isSymbolicLink()) continue;
} catch {
@@ -605,25 +670,14 @@ export function relocateInPlaceCanonical(opts: {
try {
resolved = realpathSync(sib);
} catch {
- resolved = null; // dangling — re-point it
- }
- // Re-point when: dangling, pointed at the old source, or resolves to the
- // new dest THROUGH another link (chain) — links always point DIRECTLY at
- // the real dir, so removing any one link can never strand another.
- if (resolved === null || resolved === canonicalAbs || resolved === resolve(dest)) {
- tracedRmSync(sib, { recursive: true, force: true });
- tracedSymlinkSync(skillLinkTarget(cwd, dirname(sib), dest), sib, 'dir');
+ resolved = null; // dangling
}
+ if (resolved !== null && !claim.has(resolved)) continue;
+ tracedRmSync(sib, { recursive: true, force: true });
+ tracedSymlinkSync(skillLinkTarget(cwd, dirname(sib), target), sib, 'dir');
}
- return { ok: true, newAbs: dest };
}
-/** Every install-target host (editors with a project dir + the .agents hub). */
-const ALL_TARGET_HOSTS: readonly SkillHostId[] = [
- 'agents',
- ...(PROJECT_SKILL_EDITOR_IDS as readonly EditorId[]),
-];
-
/**
* Uninstall counterpart of {@link projectInPlaceSkill}: remove a target editor's
* occurrence ONLY when doing so loses nothing — a symlink, or a real dir
@@ -667,22 +721,11 @@ export function removeInPlaceSkillCopies(opts: {
}
// Removing an occurrence (real copy OR a link other links chained through)
// can orphan sibling links — re-point survivors at the canonical.
+ // Dangling only: no `alsoClaim`, so a link still aimed at something real
+ // keeps pointing there. Widening this is the regression the shared spine has
+ // to make hard.
if (removed.length > 0) {
- for (const host of ALL_TARGET_HOSTS) {
- const sib = skillTargetDir(cwd, host, name, roots);
- if (sib === null) continue;
- try {
- if (!lstatSync(sib).isSymbolicLink()) continue;
- } catch {
- continue;
- }
- try {
- realpathSync(sib);
- } catch {
- tracedRmSync(sib, { recursive: true, force: true });
- tracedSymlinkSync(skillLinkTarget(cwd, dirname(sib), canonicalAbs), sib, 'dir');
- }
- }
+ repointSiblingLinks({ name, cwd, roots, target: canonicalAbs });
}
return removed;
}