core

@obsidian-vfs/core

Shared engine for Obsidian VFS. Provides obs:// URI resolution, file I/O, Obsidian CLI integration, LRU caching, and content processing used by all consumer packages.

Responsibilities

• URI resolution — obs:// scheme handling, @obs: context mentions, /obs: skill mentions, [[wikilink]] resolution.
• File I/O — Direct reads via node:fs (bypassing the CLI for performance), directory enumeration, file watching.
• Obsidian CLI wrapper — Async queue-serialized calls to the obsidian binary for search, backlinks, vault discovery. JSON and plain-text response parsing.
• Content processing — Section slicing by #heading, [[wikilink]] scrubbing to obs:// URIs, ![[embed]] transclusion, Markdown link parsing.
• Frontmatter — Extraction, curation, and formatting of YAML frontmatter. Model field mapping to Claude model identifiers via mapModelToClaude().
• Mount tree — Pure visibility logic for partial autoMount paths. Used by VSCode to compute files.exclude sub-directory exclusions that match tree view visibility.
• Caching — Generic LRUCache<K, V> with TTL expiration.
• Security — path.resolve + vault-root prefix check on all I/O. Symlink rejection outside vault. allowed/blocked enforcement on general vault content; agents/skills implicitly allowed.
• Configuration — Vault config from .obsidian/obsidian-vfs.json (agents, skills, allowed, blocked).

Exports

The package exposes two entry points:

Entry	Path	Purpose
.	dist/index.js	All production exports
./testing	dist/test-helpers.js	Test utilities and mocks

Testing Utilities

The ./testing entry point provides test doubles for consumer packages:

Utility	Description
mockCLI(overrides?)	Fully-stubbed ObsidianCLI mock with optional per-method overrides
mockFsFunction(fn)	Type-safe cast wrapper for mocked node:fs/promises functions
makeLocalIndexTrackerWith(methodName, result, extraMethods?, contextOverrides?)	Build a mock LocalIndexTracker whose single method resolves to a given VFSResult
makeDiscoveredResource(overrides?)	Build a DiscoveredResource with sensible defaults

Key Exports

Category	Symbols
Resolution	resolveMention, resolveSkillMention, resolveWikilink, normalizeMention, parseSection
File I/O	readVirtualFile, listMarkdownFiles, listFolders, readDirectory
CLI	ObsidianCLI, resolveExecConfig, resolveCliPath
Content	sliceContent, scrubWikilinks, processContent, resolveEmbeds, maskCodeRegions
Frontmatter	extractFrontmatter, extractCuratedFrontmatter, remapModelLine, mapModelToClaude
Types	VFSResult, VFSError, VFSConfig, ErrorCode, MentionKind
Mount tree	buildMountTree, MountNode
Utilities	LRUCache, LocalIndexTracker, AsyncQueue
Constants	URI_SCHEME, URI_PREFIX, MENTION_PREFIX, SKILL_PREFIX

Result Types

All fallible operations return VFSResult<T>, a discriminated union:

type VFSResult<T> = { ok: true; value: T } | { ok: false; error: VFSError };

No nulls, no thrown exceptions for expected failures.

CLI Parsing Convention

The Obsidian CLI returns different formats per command:

• search, backlinks → JSON
• vault, files, folders, read → plain text
• Exit code is always 0; detect errors via Error: prefix in stdout.

Degraded Mode

When Obsidian is not running, the core falls back to node:fs for reads and enumeration. Search and wikilink resolution are unavailable in this mode.