Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): show symlinked directories in the file tree (#1976)
Andrew Mikofalvyacc4c50394eb
diff --git a/.changeset/fix-directory-symlink-alias-tree.md b/.changeset/fix-directory-symlink-alias-tree.mdnew file mode 100644index 000000000..89c52b373--- /dev/null+++ b/.changeset/fix-directory-symlink-alias-tree.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Fix directory symlinks (aliased folders) silently disappearing from the file tree. When a content directory contained a symlinked directory pointing at an already-indexed subtree, the boot-time index walk dropped it — the folder showed empty (its children were filed under the canonical path) or vanished entirely (a second symlink to the same inode). Symlinked directories now surface their full contents in the sidebar, mirroring the canonical folder. The index stores one lightweight edge per symlinked directory (alias prefix → canonical prefix) instead of materializing every descendant, so a content directory with many cross-linked mirrors (e.g. skill farms) stays memory-bounded; the subtree is projected under each alias prefix at `/api/documents` time. Alias rows carry the canonical document identity, so opening one reads and writes the canonical file rather than a second CRDT document over the same inode.diff --git a/packages/app/src/components/FileTree.tsx b/packages/app/src/components/FileTree.tsxindex 988dd5c82..fe5f9595d 100644--- a/packages/app/src/components/FileTree.tsx+++ b/packages/app/src/components/FileTree.tsx@@ -124,6 +124,7 @@ import { selectTrashConfirmCopy, trashTargetDisplayName } from '@/components/filimport {type DocumentEntry,type FileEntry,+ type FolderEntry,filterVisibleEntries,isAssetEntry,isDocumentEntry,@@ -1425,24 +1426,38 @@ export function FileTree({ ref }: { ref?: Ref<FileTreeHandle | null> }) {},onSelectionChange: (selectedPaths) => handleSelectionChangeRef.current(selectedPaths),renderRowDecoration: ({ item }) => {- if (item.kind !== 'file') return null;- const doc = documentsRef.current.find(- (entry): entry is DocumentEntry =>- isDocumentEntry(entry) && docNameToTreePath(entry.docName, entry.docExt) === item.path,+ if (item.kind === 'file') {+ const doc = documentsRef.current.find(+ (entry): entry is DocumentEntry =>+ isDocumentEntry(entry) && docNameToTreePath(entry.docName, entry.docExt) === item.path,+ );+ if (doc?.isSymlink) {+ const targetPath = doc.targetPath;+ return {+ icon: LINK_DECORATION_ICON_ID,+ title: targetPath ? t`Symlink to ${targetPath}` : t`Symlink`,+ };+ }+ if (isAgentTreePath(item.path)) {+ return {+ icon: AGENT_DECORATION_ICON_ID,+ title: t`Agent configuration file`,+ };+ }+ return null;+ }+ const folder = documentsRef.current.find(+ (entry): entry is FolderEntry =>+ isFolderEntry(entry) &&+ folderPathToTreeDirectoryPath(entry.path) === folderPathToTreeDirectoryPath(item.path),);- if (doc?.isSymlink) {- const targetPath = doc.targetPath;+ if (folder?.isSymlink) {+ const targetPath = folder.targetPath;return {icon: LINK_DECORATION_ICON_ID,title: targetPath ? t`Symlink to ${targetPath}` : t`Symlink`,};}- if (isAgentTreePath(item.path)) {- return {- icon: AGENT_DECORATION_ICON_ID,- title: t`Agent configuration file`,- };- }return null;},});diff --git a/packages/app/src/components/file-tree-utils.test.ts b/packages/app/src/components/file-tree-utils.test.tsindex 780ea6a1d..506179f25 100644--- a/packages/app/src/components/file-tree-utils.test.ts+++ b/packages/app/src/components/file-tree-utils.test.ts@@ -238,7 +238,41 @@ describe('toFileEntries', () => {modified,referencedBy: ['brain/note'],},- { kind: 'folder', path: 'team', size: 0, modified, hasChildren: true },+ {+ kind: 'folder',+ path: 'team',+ size: 0,+ modified,+ hasChildren: true,+ isSymlink: false,+ targetPath: null,+ },+ ]);+ });++ test('carries isSymlink + targetPath through for a symlinked folder', () => {+ const wire = [+ DocumentListEntrySchema.parse({+ kind: 'folder',+ path: 'alias-A',+ size: 0,+ modified,+ hasChildren: true,+ isSymlink: true,+ canonicalDocName: 'canonical-folder',+ targetPath: 'canonical-folder',+ }),+ ];+ expect(toFileEntries(wire)).toEqual([+ {+ kind: 'folder',+ path: 'alias-A',+ size: 0,+ modified,+ hasChildren: true,+ isSymlink: true,+ targetPath: 'canonical-folder',+ },]);});diff --git a/packages/app/src/components/file-tree-utils.ts b/packages/app/src/components/file-tree-utils.tsindex 7078d3f33..74c916334 100644--- a/packages/app/src/components/file-tree-utils.ts+++ b/packages/app/src/components/file-tree-utils.ts@@ -21,12 +21,14 @@ interface AssetEntry {referencedBy?: string[];}-interface FolderEntry {+export interface FolderEntry {kind: 'folder';path: string;size: number;modified: string;hasChildren?: boolean;+ isSymlink?: boolean;+ targetPath?: string | null;}export type FileEntry = DocumentEntry | AssetEntry | FolderEntry;@@ -107,6 +109,8 @@ export function toFileEntries(entries: readonly DocumentListEntry[]): FileEntry[size: entry.size,modified: entry.modified,hasChildren: entry.hasChildren,+ isSymlink: entry.isSymlink,+ targetPath: entry.targetPath,});break;default: {diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex 3e03fca6b..88e627be2 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -1051,6 +1051,85 @@ export async function* streamShowAllEntries(continue;}+ if (entry.isSymbolicLink()) {+ const linkAbs = `${absDir}/${entry.name}`;+ let canonical: string;+ try {+ canonical = await realpath(linkAbs);+ } catch (err) {+ console.warn(`[document-list][showAll] symlink realpath failed for ${linkAbs}:`, err);+ continue;+ }+ if (!isInsideContentDir(canonical)) {+ console.warn(+ `[document-list][showAll] refusing symlink-escape ${linkAbs} -> ${canonical}`,+ );+ continue;+ }+ let canonStat: import('node:fs').Stats;+ try {+ canonStat = await stat(canonical);+ } catch (err) {+ console.warn(+ `[document-list][showAll] symlink target stat failed for ${linkAbs}:`,+ err,+ );+ continue;+ }+ const targetRel = relative(contentDir, canonical);+ if (canonStat.isDirectory()) {+ if (contentFilter.isDirExcluded(relPath, { bypassFilters: true })) continue;+ if (!passesDirFilter(relPath)) continue;+ emitted += 1;+ yield {+ kind: 'folder',+ path: relPath,+ size: 0,+ modified: canonStat.mtime.toISOString(),+ docExt: '.md',+ isSymlink: true,+ canonicalDocName: targetRel,+ targetPath: targetRel,+ hasChildren: await probeHasChildren(canonical, relPath),+ };+ continue;+ }+ if (!canonStat.isFile()) continue;+ if (contentFilter.isExcluded(relPath, { bypassFilters: true })) continue;+ if (!passesDirFilter(relPath)) continue;+ emitted += 1;+ if (isSupportedDocFile(entry.name)) {+ const docName = relPath.replace(/\.(md|mdx)$/i, '');+ yield {+ kind: 'document',+ docName,+ docExt: getDocExtension(docName),+ size: canonStat.size,+ modified: canonStat.mtime.toISOString(),+ isSymlink: true,+ canonicalDocName: targetRel.replace(/\.(md|mdx)$/i, ''),+ targetPath: targetRel,+ };+ } else {+ const assetExt = synthesizeShowAllAssetExt(entry.name);+ yield {+ kind: 'asset',+ docName: relPath,+ docExt: assetExt,+ path: relPath,+ assetExt,+ mediaKind: mediaKindForSidebarAssetExtension(assetExt),+ referencedBy: [],+ size: canonStat.size,+ modified: canonStat.mtime.toISOString(),+ isSymlink: true,+ canonicalDocName: null,+ targetPath: targetRel,+ };+ }+ continue;+ }+if (!entry.isFile()) continue;if (contentFilter.isExcluded(relPath, { bypassFilters: true })) continue;if (!passesDirFilter(relPath)) continue;@@ -1580,6 +1659,7 @@ export interface ApiExtensionOptions {getFolderIndex?: () => ReadonlyMap<string, FolderIndexEntry>;onReferencedAssetsCacheInvalidator?: (invalidate: () => void) => void;getAliasMap?: () => ReadonlyMap<string, string>;+ getFolderAliasIndex?: () => ReadonlyMap<string, string>;rescanFiles?: () => void | Promise<void>;enableTestRoutes?: boolean;shadowRef?: ShadowRef;@@ -1673,6 +1753,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {getFolderIndex,onReferencedAssetsCacheInvalidator,getAliasMap,+ getFolderAliasIndex,rescanFiles,enableTestRoutes = false,shadowRef,@@ -4086,6 +4167,97 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {}}+ const folderAliasIndex = getFolderAliasIndex?.() ?? new Map<string, string>();+ if (folderAliasIndex.size > 0) {+ const passesDirFilter = (p: string): boolean =>+ !dir || p === dir || p.startsWith(`${dir}/`);+ const aliasesByCanonical = new Map<string, string[]>();+ for (const [aliasPrefix, canonicalPrefix] of folderAliasIndex) {+ const arr = aliasesByCanonical.get(canonicalPrefix);+ if (arr) arr.push(aliasPrefix);+ else aliasesByCanonical.set(canonicalPrefix, [aliasPrefix]);+ }+ for (const [canonicalPrefix, aliasPrefixes] of aliasesByCanonical) {+ const canonRoot = folderIndex.get(canonicalPrefix);+ const rootTarget = canonRoot+ ? relative(contentDir, canonRoot.canonicalPath)+ : canonicalPrefix;+ for (const aliasPrefix of aliasPrefixes) {+ if (!passesDirFilter(aliasPrefix)) continue;+ documents.push({+ kind: 'folder',+ path: aliasPrefix,+ size: 0,+ modified: canonRoot?.modified ?? '1970-01-01T00:00:00.000Z',+ docExt: '.md',+ isSymlink: true,+ canonicalDocName: canonicalPrefix,+ targetPath: rootTarget,+ });+ }+ }+ const projectChild = (name: string, emit: (aliasName: string) => void): void => {+ for (+ let slash = name.indexOf('/');+ slash !== -1;+ slash = name.indexOf('/', slash + 1)+ ) {+ const aliasPrefixes = aliasesByCanonical.get(name.slice(0, slash));+ if (!aliasPrefixes) continue;+ const rest = name.slice(slash);+ for (const aliasPrefix of aliasPrefixes) {+ const aliasName = `${aliasPrefix}${rest}`;+ if (passesDirFilter(aliasName)) emit(aliasName);+ }+ }+ };+ for (const [folderPath, fEntry] of folderIndex) {+ projectChild(folderPath, (aliasName) => {+ documents.push({+ kind: 'folder',+ path: aliasName,+ size: 0,+ modified: fEntry.modified,+ docExt: '.md',+ isSymlink: true,+ canonicalDocName: folderPath,+ targetPath: relative(contentDir, fEntry.canonicalPath),+ });+ });+ }+ for (const [docName, dEntry] of allFiles) {+ projectChild(docName, (aliasName) => {+ const targetRelPath = relative(contentDir, dEntry.canonicalPath);+ if (dEntry.kind === 'markdown') {+ documents.push({+ kind: 'document',+ docName: aliasName,+ docExt: getDocExtension(docName),+ size: dEntry.size,+ modified: dEntry.modified,+ isSymlink: true,+ canonicalDocName: docName,+ targetPath: targetRelPath,+ });+ } else {+ const assetExt = synthesizeShowAllAssetExt(aliasName);+ documents.push({+ kind: 'file',+ docName: aliasName,+ path: aliasName,+ docExt: `.${assetExt}`,+ assetExt,+ size: dEntry.size,+ modified: dEntry.modified,+ isSymlink: true,+ canonicalDocName: docName,+ targetPath: targetRelPath,+ });+ }+ });+ }+ }+documents.sort((a, b) => {const aPath = a.kind === 'folder' ? (a.path ?? '') : (a.docName ?? a.path ?? '');const bPath = b.kind === 'folder' ? (b.path ?? '') : (b.docName ?? b.path ?? '');diff --git a/packages/server/src/file-watcher.test.ts b/packages/server/src/file-watcher.test.tsindex 1ea2ec262..868bd6123 100644--- a/packages/server/src/file-watcher.test.ts+++ b/packages/server/src/file-watcher.test.ts@@ -1118,6 +1118,37 @@ describe('startWatcher symlink handling', () => {}});+ test('records a folder-alias edge for a symlinked directory without materializing its subtree', async () => {+ const canonicalDir = resolve(contentDir, 'canonical');+ mkdirSync(canonicalDir, { recursive: true });+ writeFileSync(resolve(canonicalDir, 'note.md'), '# Note\n');+ mkdirSync(resolve(canonicalDir, 'sub'), { recursive: true });+ writeFileSync(resolve(canonicalDir, 'sub', 'deep.md'), '# Deep\n');+ symlinkSync(canonicalDir, resolve(contentDir, 'aliasA'));+ symlinkSync(canonicalDir, resolve(contentDir, 'aliasB'));++ const handle = await startWatcher(contentDir, async () => {});+ try {+ const folderAliasIndex = handle.getFolderAliasIndex();+ expect(folderAliasIndex.get('aliasA')).toBe('canonical');+ expect(folderAliasIndex.get('aliasB')).toBe('canonical');++ const index = handle.getFileIndex();+ expect(index.has('canonical/note')).toBe(true);+ expect(index.has('canonical/sub/deep')).toBe(true);+ expect(index.has('aliasA/note')).toBe(false);+ expect(index.has('aliasB/sub/deep')).toBe(false);++ const folderIndex = handle.getFolderIndex();+ expect(folderIndex.has('canonical')).toBe(true);+ expect(folderIndex.has('canonical/sub')).toBe(true);+ expect(folderIndex.has('aliasA')).toBe(false);+ expect(folderIndex.has('aliasB')).toBe(false);+ } finally {+ await handle.unsubscribe();+ }+ });+test('skips broken symlinks during startup walk', async () => {const linkPath = resolve(contentDir, 'broken.md');symlinkSync(resolve(contentDir, 'nonexistent.md'), linkPath);diff --git a/packages/server/src/file-watcher.ts b/packages/server/src/file-watcher.tsindex 77bf71ae8..2da242e45 100644--- a/packages/server/src/file-watcher.ts+++ b/packages/server/src/file-watcher.ts@@ -104,6 +104,7 @@ export interface WatcherHandle {getFileIndexGeneration: () => number;getFolderIndex: () => ReadonlyMap<string, FolderIndexEntry>;getAliasMap: () => ReadonlyMap<string, string>;+ getFolderAliasIndex: () => ReadonlyMap<string, string>;mutateFileIndex: (event: DiskEvent) => void;pruneFileIndexNowExcluded: () => number;pruneFolderIndexNowExcluded: () => number;@@ -441,6 +442,7 @@ async function seedLastKnownHashes(fileIndex: Map<string, FileIndexEntry>,folderIndex: Map<string, FolderIndexEntry>,aliasMap: Map<string, string>,+ folderAliasIndex: Map<string, string>,visitedInodes?: Set<number>,): Promise<void> {const visited = visitedInodes ?? new Set<number>();@@ -489,6 +491,14 @@ async function seedLastKnownHashes(if (existing && !existing.aliases.includes(aliasDocName)) {existing.aliases.push(aliasDocName);}+ } else if (canonStat.isDirectory()) {+ const relPath = contentRelativePath(contentDir, fullPath);+ if (!contentFilter || (relPath && !contentFilter.isDirExcluded(relPath))) {+ folderAliasIndex.set(+ pathToDocName(fullPath, contentDir),+ pathToDocName(canonical, contentDir),+ );+ }}continue;}@@ -499,7 +509,10 @@ async function seedLastKnownHashes(if (contentFilter) {if (!relPath || contentFilter.isDirExcluded(relPath)) continue;}- upsertFolderIndexEntry(folderIndex, contentDir, fullPath, canonStat, canonical);+ folderAliasIndex.set(+ pathToDocName(fullPath, contentDir),+ pathToDocName(canonical, contentDir),+ );await seedLastKnownHashes(canonical,contentDir,@@ -507,6 +520,7 @@ async function seedLastKnownHashes(fileIndex,folderIndex,aliasMap,+ folderAliasIndex,visited,);} else if (canonStat.isFile() && isSupportedDocFile(entry.name)) {@@ -578,6 +592,7 @@ async function seedLastKnownHashes(fileIndex,folderIndex,aliasMap,+ folderAliasIndex,visited,);} else if (lst.isFile() && isSupportedDocFile(entry.name)) {@@ -1210,6 +1225,7 @@ export async function startWatcher(const fileIndex = new Map<string, FileIndexEntry>();const folderIndex = new Map<string, FolderIndexEntry>();const aliasMap = new Map<string, string>();+ const folderAliasIndex = new Map<string, string>();let fileIndexGeneration = 0;let cachedMarkdownView: ReadonlyMap<string, FileIndexEntry> | null = null;@@ -1225,6 +1241,7 @@ export async function startWatcher(fileIndex,folderIndex,aliasMap,+ folderAliasIndex,);bumpFileIndexGeneration();@@ -1293,6 +1310,9 @@ export async function startWatcher(getAliasMap() {return aliasMap;},+ getFolderAliasIndex() {+ return folderAliasIndex;+ },mutateFileIndex(event) {updateFileIndex(event, fileIndex);bumpFileIndexGeneration();@@ -1333,6 +1353,7 @@ export async function startWatcher(fileIndex,folderIndex,aliasMap,+ folderAliasIndex,);bumpFileIndexGeneration();},diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex 6a253261b..7e15bf69e 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -687,6 +687,7 @@ export function createServer(options: ServerOptions): ServerInstance {mutateFileIndex: (event) => watcher?.mutateFileIndex(event),getFolderIndex: () => (watcher ? watcher.getFolderIndex() : new Map()),getAliasMap: () => (watcher ? watcher.getAliasMap() : new Map()),+ getFolderAliasIndex: () => (watcher ? watcher.getFolderAliasIndex() : new Map()),rescanFiles: () => watcher?.rescanFromDisk(),enableTestRoutes,shadowRef,diff --git a/packages/server/src/showall-stream.test.ts b/packages/server/src/showall-stream.test.tsindex ff62f4dba..28890f0e4 100644--- a/packages/server/src/showall-stream.test.ts+++ b/packages/server/src/showall-stream.test.ts@@ -1,5 +1,12 @@import { afterEach, describe, expect, spyOn, test } from 'bun:test';-import { chmodSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';+import {+ chmodSync,+ mkdirSync,+ mkdtempSync,+ realpathSync,+ symlinkSync,+ writeFileSync,+} from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import { ASSET_EXTENSIONS, type DocumentListEntry } from '@inkeep/open-knowledge-core';@@ -330,3 +337,74 @@ describe('streamShowAllEntries — .base/.canvas mediaKind', () => {expect(ASSET_EXTENSIONS.has('canvas')).toBe(false);});});++describe('streamShowAllEntries — symlinked directories', () => {+ function makeSymlinkDirFixture(): string {+ const dir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-showall-symdir-')));+ const canonical = join(dir, 'canonical-folder');+ mkdirSync(canonical);+ writeFileSync(join(canonical, 'note-one.md'), '# one\n');+ mkdirSync(join(canonical, 'nested'));+ writeFileSync(join(canonical, 'nested', 'deep.md'), '# deep\n');+ symlinkSync(canonical, join(dir, 'alias-A'));+ symlinkSync(canonical, join(dir, 'alias-B'));+ return dir;+ }++ function pathsOf(entries: DocumentListEntry[]): string[] {+ return entries.map((e) => (e.kind === 'folder' ? (e.path ?? '') : (e.docName ?? e.path ?? '')));+ }++ test('emits each symlinked directory as a folder without recursing into it', async () => {+ const dir = makeSymlinkDirFixture();+ const { entries } = await drain(streamShowAllEntries(streamOptsFor(dir, 50_000)));+ const folders = new Map(entries.filter((e) => e.kind === 'folder').map((e) => [e.path, e]));+ for (const alias of ['alias-A', 'alias-B']) {+ const f = folders.get(alias);+ expect(f).toBeDefined();+ expect(f?.isSymlink).toBe(true);+ expect(f?.targetPath).toBe('canonical-folder');+ expect(f?.hasChildren).toBe(true);+ }+ const paths = pathsOf(entries);+ expect(paths).toContain('canonical-folder/note-one');+ expect(paths).toContain('canonical-folder/nested/deep');+ expect(paths.some((p) => p.startsWith('alias-A/'))).toBe(false);+ expect(paths.some((p) => p.startsWith('alias-B/'))).toBe(false);+ });++ test('expanding a symlinked directory lists the canonical children under the alias prefix', async () => {+ const dir = makeSymlinkDirFixture();+ const { entries } = await drain(+ streamShowAllEntries({ ...streamOptsFor(dir, 50_000), dirFilter: 'alias-A' }),+ );+ const paths = pathsOf(entries);+ expect(paths).toContain('alias-A/note-one');+ expect(paths).toContain('alias-A/nested');+ });++ test('refuses a symlinked directory whose target escapes contentDir', async () => {+ const dir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-showall-symesc-')));+ const outside = realpathSync(mkdtempSync(join(tmpdir(), 'ok-showall-outside-')));+ writeFileSync(join(outside, 'secret.md'), '# secret\n');+ symlinkSync(outside, join(dir, 'escape'));+ const { entries } = await drain(streamShowAllEntries(streamOptsFor(dir, 50_000)));+ const paths = pathsOf(entries);+ expect(paths).not.toContain('escape');+ expect(paths.some((p) => p.includes('secret'))).toBe(false);+ });++ test('does not infinitely recurse on cyclic symlinked directories', async () => {+ const dir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-showall-symcycle-')));+ mkdirSync(join(dir, 'A'));+ mkdirSync(join(dir, 'B'));+ writeFileSync(join(dir, 'A', 'a.md'), '# a\n');+ writeFileSync(join(dir, 'B', 'b.md'), '# b\n');+ symlinkSync(join(dir, 'B'), join(dir, 'A', 'to-b'));+ symlinkSync(join(dir, 'A'), join(dir, 'B', 'to-a'));+ const { entries, truncated } = await drain(streamShowAllEntries(streamOptsFor(dir, 50_000)));+ const toB = entries.find((e) => e.kind === 'folder' && e.path === 'A/to-b');+ expect(toB?.isSymlink).toBe(true);+ expect(truncated).toBe(false);+ });+});