Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.tsindex 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 guardexpect(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.tsindex 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;}