fix(core): link source contents directly into docset dir (no extra subfolder)

Fixes two related bugs in createSymlinks:

1. Path with no trailing slash (eg. /temp/demo): the directory name "demo"
   was appended as a subfolder, producing demo-docset/demo/ instead of
   exposing the contents at the docset root.

2. Path with trailing slash (eg. /temp/demo/): split("/").pop() returned
   an empty string, which fell back to the hardcoded name "unknown",
   producing demo-docset/unknown/.

Root cause: the function symlinked the source directory itself, deriving
the link name from the path string.

Fix: iterate over the entries inside the source directory and create one
symlink per entry directly inside targetDir.  This matches the behaviour
of git_repo and archive sources, which also populate the docset root
without an extra named subfolder.  The trailing-slash case is a non-issue
because we now read directory contents rather than parsing the path string.

https://claude.ai/code/session_014fPGYkZQTaWzSuLcDejZQD

Author: claude

packages/content-loader/src/docset-init.ts

@@ -1,5 +1,5 @@
 /**
- * Shared docset initialization logic used by both the CLI and MCP server.
+ * Docset initialization logic shared between CLI and MCP server.
  */
 
 import { promises as fs } from "node:fs";
@@ -39,13 +39,8 @@ export interface InitDocsetOptions {
 }
 
 /**
- * Initialize the sources for a docset: download / symlink content, write
- * metadata files.  Pure logic — no console output, no config loading.
- *
- * @param docsetId   Docset identifier (used in metadata)
- * @param docset     Already-resolved DocsetConfig
- * @param configPath Absolute path to the `.knowledge/config.yaml` file
- * @param options    Optional flags and progress callback
+ * Download / symlink all sources for a docset and write metadata files.
+ * Does not load config or produce console output — callers handle both.
  */
 export async function initDocset(
   docsetId: string,
@@ -61,13 +56,12 @@ export async function initDocset(
 
   const localPath = calculateLocalPath(docset, configPath);
 
-  // Check if already initialized
   let existsAlready = false;
   try {
     const stat = await fs.stat(localPath);
     if (stat.isDirectory()) existsAlready = true;
   } catch {
-    // Directory doesn't exist yet — that's fine
+    // not yet created
   }
 
   if (existsAlready && !force) {

packages/core/src/__tests__/cleanup.test.ts

@@ -33,7 +33,6 @@ describe("Safe Directory Cleanup", () => {
 
   describe("safelyClearDirectory", () => {
     it("should clear directory with regular files", async () => {
-      // Create some files
       await fs.writeFile(path.join(targetDir, "file1.txt"), "content1");
       await fs.writeFile(path.join(targetDir, "file2.txt"), "content2");
       await fs.mkdir(path.join(targetDir, "subdir"), { recursive: true });
@@ -42,10 +41,8 @@ describe("Safe Directory Cleanup", () => {
         "content3",
       );
 
-      // Clear directory
       await safelyClearDirectory(targetDir);
 
-      // Directory should not exist
       const exists = await fs
         .access(targetDir)
         .then(() => true)
@@ -54,78 +51,63 @@ describe("Safe Directory Cleanup", () => {
     });
 
     it("should handle non-existent directory gracefully", async () => {
-      const nonExistent = path.join(testDir, "does-not-exist");
-
-      // Should not throw
-      await expect(safelyClearDirectory(nonExistent)).resolves.not.toThrow();
+      await expect(
+        safelyClearDirectory(path.join(testDir, "does-not-exist")),
+      ).resolves.not.toThrow();
     });
 
     it("should clear directory with symlinks without deleting source files", async () => {
-      // Create source file
       const srcFolder = path.join(sourceDir, "src");
       await fs.mkdir(srcFolder, { recursive: true });
       const sourceFile = path.join(srcFolder, "important.js");
       await fs.writeFile(sourceFile, "IMPORTANT DATA");
 
-      // Create symlink
       await createSymlinks(["src"], targetDir, sourceDir);
 
-      // Verify symlink exists
-      const symlinkPath = path.join(targetDir, "src");
-      const stat = await fs.lstat(symlinkPath);
-      expect(stat.isSymbolicLink()).toBe(true);
+      const symlinkPath = path.join(targetDir, "important.js");
+      expect((await fs.lstat(symlinkPath)).isSymbolicLink()).toBe(true);
 
-      // Clear target directory
       await safelyClearDirectory(targetDir);
 
-      // Source file must still exist!
-      const sourceContent = await fs.readFile(sourceFile, "utf-8");
-      expect(sourceContent).toBe("IMPORTANT DATA");
-
-      // Target directory should be gone
-      const targetExists = await fs
-        .access(targetDir)
-        .then(() => true)
-        .catch(() => false);
-      expect(targetExists).toBe(false);
+      // Source must survive removal of the docset directory
+      expect(await fs.readFile(sourceFile, "utf-8")).toBe("IMPORTANT DATA");
+      expect(
+        await fs
+          .access(targetDir)
+          .then(() => true)
+          .catch(() => false),
+      ).toBe(false);
     });
   });
 
   describe("containsSymlinks", () => {
     it("should detect symlinks", async () => {
-      // Create a source folder
       const srcFolder = path.join(sourceDir, "src");
       await fs.mkdir(srcFolder, { recursive: true });
       await fs.writeFile(path.join(srcFolder, "file.js"), "content");
 
-      // Create symlink
       await createSymlinks(["src"], targetDir, sourceDir);
 
-      const hasSymlinks = await containsSymlinks(targetDir);
-      expect(hasSymlinks).toBe(true);
+      expect(await containsSymlinks(targetDir)).toBe(true);
     });
 
     it("should return false for directory with no symlinks", async () => {
       await fs.writeFile(path.join(targetDir, "regular.txt"), "content");
 
-      const hasSymlinks = await containsSymlinks(targetDir);
-      expect(hasSymlinks).toBe(false);
+      expect(await containsSymlinks(targetDir)).toBe(false);
     });
 
     it("should return false for non-existent directory", async () => {
-      const hasSymlinks = await containsSymlinks(path.join(testDir, "nope"));
-      expect(hasSymlinks).toBe(false);
+      expect(await containsSymlinks(path.join(testDir, "nope"))).toBe(false);
     });
   });
 
   describe("getDirectoryInfo", () => {
     it("should count different entry types", async () => {
-      // Create mixed content
       await fs.writeFile(path.join(targetDir, "file1.txt"), "content");
       await fs.writeFile(path.join(targetDir, "file2.txt"), "content");
       await fs.mkdir(path.join(targetDir, "subdir"), { recursive: true });
 
-      // Create symlink
       const srcFolder = path.join(sourceDir, "src");
       await fs.mkdir(srcFolder, { recursive: true });
       await fs.writeFile(path.join(srcFolder, "file.js"), "content");

packages/core/src/__tests__/local-folder-safety.test.ts

@@ -15,15 +15,13 @@ describe("Local Folder Cleanup Safety", () => {
   let sourceFile: string;
 
   beforeEach(async () => {
-    // Create test directories
     testDir = path.join(tmpdir(), `agentic-safety-test-${Date.now()}`);
     sourceDir = path.join(testDir, "source");
     targetDir = path.join(testDir, "target");
 
     await fs.mkdir(sourceDir, { recursive: true });
     await fs.mkdir(targetDir, { recursive: true });
 
-    // Create a source directory with actual files
     const actualSourceFolder = path.join(sourceDir, "src");
     await fs.mkdir(actualSourceFolder, { recursive: true });
     sourceFile = path.join(actualSourceFolder, "important-file.js");
@@ -35,34 +33,26 @@ describe("Local Folder Cleanup Safety", () => {
   });
 
   it("CRITICAL: should NOT delete source files when removing symlinks", async () => {
-    // Create symlink to source directory
     await createSymlinks(["src"], targetDir, sourceDir);
 
-    // Verify symlink was created
-    const symlinkPath = path.join(targetDir, "src");
-    const linkStat = await fs.lstat(symlinkPath);
-    expect(linkStat.isSymbolicLink()).toBe(true);
-
-    // Verify we can access the source file through the symlink
-    const fileViaSymlink = path.join(symlinkPath, "important-file.js");
-    const content = await fs.readFile(fileViaSymlink, "utf-8");
-    expect(content).toBe("CRITICAL DATA - DO NOT DELETE");
+    const symlinkPath = path.join(targetDir, "important-file.js");
+    expect((await fs.lstat(symlinkPath)).isSymbolicLink()).toBe(true);
+    expect(await fs.readFile(symlinkPath, "utf-8")).toBe(
+      "CRITICAL DATA - DO NOT DELETE",
+    );
 
-    // Remove symlinks
     await removeSymlinks(targetDir);
 
-    // CRITICAL: Source file must still exist!
+    // CRITICAL: removing the symlink must never touch the source
     const stillExists = await fs
       .access(sourceFile)
       .then(() => true)
       .catch(() => false);
     expect(stillExists).toBe(true);
+    expect(await fs.readFile(sourceFile, "utf-8")).toBe(
+      "CRITICAL DATA - DO NOT DELETE",
+    );
 
-    // Verify content is unchanged
-    const originalContent = await fs.readFile(sourceFile, "utf-8");
-    expect(originalContent).toBe("CRITICAL DATA - DO NOT DELETE");
-
-    // Symlink should be gone
     const symlinkGone = await fs
       .lstat(symlinkPath)
       .then(() => false)
@@ -71,107 +61,88 @@ describe("Local Folder Cleanup Safety", () => {
   });
 
   it("CRITICAL: should NOT delete source files when clearing target directory", async () => {
-    // Create symlink
     await createSymlinks(["src"], targetDir, sourceDir);
 
-    // Verify source file exists
-    expect(await fs.readFile(sourceFile, "utf-8")).toBe(
-      "CRITICAL DATA - DO NOT DELETE",
-    );
-
-    // Simulate clearing target directory (what --force does)
-    // This is the DANGEROUS operation we need to test
+    // Simulate --force: delete the whole docset directory
     await fs.rm(targetDir, { recursive: true, force: true });
 
-    // CRITICAL: Source file must STILL exist after removing target!
+    // CRITICAL: fs.rm must not follow symlinks into the source
     const stillExists = await fs
       .access(sourceFile)
       .then(() => true)
       .catch(() => false);
-
     expect(stillExists).toBe(
       true,
       "CRITICAL FAILURE: Source file was deleted!",
     );
 
     if (stillExists) {
-      const content = await fs.readFile(sourceFile, "utf-8");
-      expect(content).toBe("CRITICAL DATA - DO NOT DELETE");
+      expect(await fs.readFile(sourceFile, "utf-8")).toBe(
+        "CRITICAL DATA - DO NOT DELETE",
+      );
     }
   });
 
   it("CRITICAL: should handle nested symlinks safely", async () => {
-    // Create nested structure in source
     const nestedDir = path.join(sourceDir, "src", "nested");
     await fs.mkdir(nestedDir, { recursive: true });
     const nestedFile = path.join(nestedDir, "nested-file.js");
     await fs.writeFile(nestedFile, "NESTED CRITICAL DATA");
 
-    // Create symlink
     await createSymlinks(["src"], targetDir, sourceDir);
-
-    // Clear target directory
     await fs.rm(targetDir, { recursive: true, force: true });
 
-    // CRITICAL: All source files must still exist
-    const sourceExists = await fs
-      .access(sourceFile)
-      .then(() => true)
-      .catch(() => false);
-    const nestedExists = await fs
-      .access(nestedFile)
-      .then(() => true)
-      .catch(() => false);
-
-    expect(sourceExists).toBe(true, "Source file was deleted!");
-    expect(nestedExists).toBe(true, "Nested source file was deleted!");
+    // CRITICAL: All source files must survive target removal
+    expect(
+      await fs
+        .access(sourceFile)
+        .then(() => true)
+        .catch(() => false),
+    ).toBe(true, "Source file was deleted!");
+    expect(
+      await fs
+        .access(nestedFile)
+        .then(() => true)
+        .catch(() => false),
+    ).toBe(true, "Nested source file was deleted!");
   });
 
   it("should safely handle mixed content (symlinks and regular files)", async () => {
-    // Create symlink
     await createSymlinks(["src"], targetDir, sourceDir);
 
-    // Add a regular file to target directory
     const regularFile = path.join(targetDir, "regular-file.txt");
     await fs.writeFile(regularFile, "This can be deleted");
 
-    // Clear target directory
     await fs.rm(targetDir, { recursive: true, force: true });
 
-    // Source file must still exist
-    const sourceExists = await fs
-      .access(sourceFile)
-      .then(() => true)
-      .catch(() => false);
-    expect(sourceExists).toBe(true);
-
-    // Target directory should be gone
-    const targetExists = await fs
-      .access(targetDir)
-      .then(() => true)
-      .catch(() => false);
-    expect(targetExists).toBe(false);
+    expect(
+      await fs
+        .access(sourceFile)
+        .then(() => true)
+        .catch(() => false),
+    ).toBe(true);
+    expect(
+      await fs
+        .access(targetDir)
+        .then(() => true)
+        .catch(() => false),
+    ).toBe(false);
   });
 
   it("should document Node.js symlink behavior", async () => {
-    // This test documents how Node.js handles symlinks with fs.rm
-    // According to Node.js docs, fs.rm should NOT follow symlinks
-
+    // fs.rm with recursive:true must NOT follow symlinks — this test pins that contract.
     await createSymlinks(["src"], targetDir, sourceDir);
-    const symlinkPath = path.join(targetDir, "src");
+    const symlinkPath = path.join(targetDir, "important-file.js");
 
-    // Verify it's a symlink
-    const stats = await fs.lstat(symlinkPath);
-    expect(stats.isSymbolicLink()).toBe(true);
+    expect((await fs.lstat(symlinkPath)).isSymbolicLink()).toBe(true);
 
-    // Remove just the symlink using fs.unlink
     await fs.unlink(symlinkPath);
 
-    // Source should still exist
-    const sourceExists = await fs
-      .access(sourceFile)
-      .then(() => true)
-      .catch(() => false);
-    expect(sourceExists).toBe(true);
+    expect(
+      await fs
+        .access(sourceFile)
+        .then(() => true)
+        .catch(() => false),
+    ).toBe(true);
   });
 });