Skip to content

Commit f9b16a0

Browse files
committed
Implement symlinks for skills
1 parent 8bec7c1 commit f9b16a0

2 files changed

Lines changed: 742 additions & 6 deletions

File tree

‎src/services/skills/SkillsManager.ts‎

Lines changed: 162 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,16 @@ export class SkillsManager {
2424
private disposables: vscode.Disposable[] = []
2525
private isDisposed = false
2626

27+
/**
28+
* Monotonic token identifying the current discovery run. Each call to
29+
* {@link discoverSkills} bumps this value; the running scan captures it and
30+
* bails out (without mutating {@link skills}) once a newer run starts or the
31+
* manager is disposed. This keeps the recursive, asynchronous scan
32+
* lifecycle-aware so a stale traversal cannot repopulate a disposed or
33+
* superseded manager.
34+
*/
35+
private discoveryGeneration = 0
36+
2737
constructor(provider: ClineProvider) {
2838
this.providerRef = new WeakRef(provider)
2939
}
@@ -41,21 +51,100 @@ export class SkillsManager {
4151
* - .roo/skills/[dirname] can be a symlink to a skill directory
4252
*/
4353
async discoverSkills(): Promise<void> {
54+
// Start a new discovery generation. Any previously running scan captured
55+
// an older token and will stop mutating state once it notices the change.
56+
const generation = ++this.discoveryGeneration
4457
this.skills.clear()
4558
const skillsDirs = await this.getSkillsDirectories()
4659

4760
for (const { dir, source, mode } of skillsDirs) {
48-
await this.scanSkillsDirectory(dir, source, mode)
61+
// Abort early if this run was superseded or the manager was disposed
62+
// while awaiting the directory list.
63+
if (!this.isCurrentGeneration(generation)) {
64+
return
65+
}
66+
// Use a fresh visited set and a fresh set of approved real roots for
67+
// each top-level scan so traversal is deduplicated within a single
68+
// root without sharing state across different source or mode roots.
69+
await this.scanSkillsDirectory(dir, source, mode, generation, 0, new Set<string>(), new Set<string>())
70+
}
71+
}
72+
73+
/**
74+
* Whether the given discovery token still identifies the active run. Returns
75+
* false once a newer {@link discoverSkills} call starts or the manager is
76+
* disposed, allowing an in-flight recursive scan to bail out without
77+
* repopulating a disposed or superseded manager.
78+
*/
79+
private isCurrentGeneration(generation: number): boolean {
80+
return !this.isDisposed && generation === this.discoveryGeneration
81+
}
82+
83+
/**
84+
* Maximum depth for recursive scanning of symlinked skill container directories.
85+
* Prevents infinite loops from circular symlinks.
86+
*/
87+
private static readonly MAX_SCAN_DEPTH = 5
88+
89+
/**
90+
* Determine whether a resolved real path is contained within one of the
91+
* approved real roots (i.e., equal to a root or nested beneath it).
92+
*
93+
* This is the trust boundary that keeps deep recursion from following a
94+
* nested symlink out to an unrelated directory. Comparison is done against
95+
* already-resolved real paths, so a symlink target that resolves outside
96+
* every approved root is rejected.
97+
*/
98+
private isContainedWithinApprovedRoot(realPath: string, approvedRoots: Set<string>): boolean {
99+
for (const root of approvedRoots) {
100+
if (realPath === root) {
101+
return true
102+
}
103+
// Ensure a true path-segment boundary (root + separator) so that
104+
// e.g. "/a/skills-private" is not treated as inside "/a/skills".
105+
const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep
106+
if (realPath.startsWith(rootWithSep)) {
107+
return true
108+
}
49109
}
110+
return false
50111
}
51112

52113
/**
53114
* Scan a skills directory for skill subdirectories.
54-
* Handles two symlink cases:
115+
* Handles symlink cases:
55116
* 1. The skills directory itself is a symlink (resolved by directoryExists using realpath)
56117
* 2. Individual skill subdirectories are symlinks
118+
* 3. Symlinked container directories that contain skill subdirectories (e.g., ln -s ../../repo/skills .roo/skills/)
119+
*
120+
* Trust boundary: the explicitly configured skills root (and the first-level
121+
* entries placed directly inside it) are the approved real roots. Deeper
122+
* directories are only scanned or loaded when their resolved real path stays
123+
* within one of those approved roots. This prevents a nested symlink inside
124+
* an already-followed container from escaping to an unrelated directory.
125+
*
126+
* @param approvedRoots - Set of resolved real paths that bound traversal.
127+
* Empty on the initial (depth 0) call; it is seeded with the configured
128+
* root's real path and each first-level entry's real path.
57129
*/
58-
private async scanSkillsDirectory(dirPath: string, source: "global" | "project", mode?: string): Promise<void> {
130+
private async scanSkillsDirectory(
131+
dirPath: string,
132+
source: "global" | "project",
133+
mode: string | undefined,
134+
generation: number,
135+
depth: number = 0,
136+
visited: Set<string> = new Set<string>(),
137+
approvedRoots: Set<string> = new Set<string>(),
138+
): Promise<void> {
139+
if (depth > SkillsManager.MAX_SCAN_DEPTH) {
140+
return
141+
}
142+
143+
// Bail out if this scan was superseded or the manager was disposed.
144+
if (!this.isCurrentGeneration(generation)) {
145+
return
146+
}
147+
59148
if (!(await directoryExists(dirPath))) {
60149
return
61150
}
@@ -64,18 +153,73 @@ export class SkillsManager {
64153
// Get the real path (resolves if dirPath is a symlink)
65154
const realDirPath = await fs.realpath(dirPath)
66155

156+
// The configured skills root is trusted by definition, even if it is
157+
// itself a symlink to an external location. Seed the approved roots
158+
// with its real path on the initial scan.
159+
if (depth === 0) {
160+
approvedRoots.add(realDirPath)
161+
}
162+
163+
// Skip directories we've already visited (by real path) to avoid
164+
// redundant scanning and infinite loops from circular symlinks.
165+
if (visited.has(realDirPath)) {
166+
return
167+
}
168+
visited.add(realDirPath)
169+
67170
// Read directory entries
68171
const entries = await fs.readdir(realDirPath)
69172

70173
for (const entryName of entries) {
174+
// Stop mutating state if a newer scan started or we were disposed
175+
// while awaiting earlier filesystem operations in this loop.
176+
if (!this.isCurrentGeneration(generation)) {
177+
return
178+
}
179+
71180
const entryPath = path.join(realDirPath, entryName)
72181

73182
// Check if this entry is a directory (follows symlinks automatically)
74183
const stats = await fs.stat(entryPath).catch(() => null)
75184
if (!stats?.isDirectory()) continue
76185

77-
// Load skill metadata - the skill name comes from the entry name (symlink name if symlinked)
78-
await this.loadSkillMetadata(entryPath, source, mode, entryName)
186+
// Resolve the entry's real path so containment is checked against
187+
// the symlink target rather than the (possibly symlinked) name.
188+
const realEntryPath = await fs.realpath(entryPath).catch(() => null)
189+
if (!realEntryPath) continue
190+
191+
// First-level entries live directly inside the configured root, so
192+
// they (and their targets) are trusted as approved roots. This
193+
// preserves support for a symlinked container placed directly under
194+
// .roo/skills (e.g., ln -s ../../repo/skills .roo/skills/).
195+
if (depth === 0) {
196+
approvedRoots.add(realEntryPath)
197+
} else if (!this.isContainedWithinApprovedRoot(realEntryPath, approvedRoots)) {
198+
// A deeper entry that resolves outside every approved root is a
199+
// nested symlink escaping the trust boundary - skip it.
200+
continue
201+
}
202+
203+
// Check if this directory contains a SKILL.md (i.e., it's a skill directory)
204+
const skillMdPath = path.join(entryPath, "SKILL.md")
205+
if (await fileExists(skillMdPath)) {
206+
// Load skill metadata - the skill name comes from the entry name (symlink name if symlinked)
207+
await this.loadSkillMetadata(entryPath, source, mode, generation, entryName)
208+
} else {
209+
// No SKILL.md found - this might be a container directory (e.g., a symlinked repo of skills)
210+
// Recursively scan it for skill subdirectories, sharing the same
211+
// visited set and approved roots so traversal stays deduplicated
212+
// and bounded within this scan.
213+
await this.scanSkillsDirectory(
214+
entryPath,
215+
source,
216+
mode,
217+
generation,
218+
depth + 1,
219+
visited,
220+
approvedRoots,
221+
)
222+
}
79223
}
80224
} catch {
81225
// Directory doesn't exist or can't be read - this is fine
@@ -87,12 +231,14 @@ export class SkillsManager {
87231
* @param skillDir - The resolved path to the skill directory (target of symlink if symlinked)
88232
* @param source - Whether this is a global or project skill
89233
* @param mode - The mode this skill is specific to (undefined for generic skills)
234+
* @param generation - The discovery generation token for the active scan
90235
* @param skillName - The skill name (from symlink name if symlinked, otherwise from directory name)
91236
*/
92237
private async loadSkillMetadata(
93238
skillDir: string,
94239
source: "global" | "project",
95-
mode?: string,
240+
mode: string | undefined,
241+
generation: number,
96242
skillName?: string,
97243
): Promise<void> {
98244
const skillMdPath = path.join(skillDir, "SKILL.md")
@@ -162,6 +308,13 @@ export class SkillsManager {
162308
const primaryMode = modeSlugs?.[0]
163309
const skillKey = this.getSkillKey(effectiveSkillName, source, primaryMode)
164310

311+
// Do not repopulate a disposed or superseded manager: bail out if a
312+
// newer discovery run started (or dispose ran) while we were reading
313+
// and parsing this skill's SKILL.md.
314+
if (!this.isCurrentGeneration(generation)) {
315+
return
316+
}
317+
165318
this.skills.set(skillKey, {
166319
name: effectiveSkillName,
167320
description,
@@ -712,6 +865,9 @@ Add your skill instructions here.
712865

713866
async dispose(): Promise<void> {
714867
this.isDisposed = true
868+
// Invalidate any in-flight discovery so a stale recursive scan cannot
869+
// repopulate the map after disposal.
870+
this.discoveryGeneration++
715871
this.disposables.forEach((d) => d.dispose())
716872
this.disposables = []
717873
this.skills.clear()

0 commit comments

Comments
 (0)