feat(vscode): switch workspace file:// with files.exclude filtering

Replace the obs:// workspace folder with a single file:// folder at the
vault root, enabling Quick Open (Cmd+P) and full-text search support.
Non-autoMount entries and blocked paths are hidden via managed
files.exclude patterns tracked in context.workspaceState.

- addVaultWorkspaceFolder now creates file:// URI at vault root
- syncFilesExclude scans vault root, excludes non-autoMount entries and
  blocked paths from vfsConfig, preserves user-set patterns
- clearManagedExcludes removes managed patterns on workspace disable
- Serialized via promise chain to prevent concurrent read-modify-write
- Graceful degradation when readdir fails (returns previous state)
- Extract CONFIG_SECTION/CONFIG_KEY constants to types.ts
- Version bump 0.2.3 → 0.3.0

Assisted-by: Claude

Author: otaviof

AGENTS.md

@@ -28,6 +28,13 @@ Style, file layout, patterns: [CONTRIBUTING.md#conventions](CONTRIBUTING.md#conv
 - **Claude plugin**: `.claude-plugin/marketplace.json`, `packages/claude-plugin/package.json`, `.claude-plugin/plugin.json` (all three must match)
 - **npm packages**: `packages/core/package.json` + `packages/cli/package.json` (must match)
 
+## VSCode: Workspace Folder Architecture
+
+- **Single `file://` workspace folder at the vault root** for Quick Open (`Cmd+P`) and `Ctrl+Shift+F` search. VSCode's file discovery and ripgrep indexer only operate on `file://` workspace folders — `obs://` workspace folders provide zero discoverability (confirmed by spike, 2026-05-15).
+- **`files.exclude` patterns** hide non-autoMount vault content from Explorer and Quick Open. Patterns are managed via `ConfigurationTarget.Workspace` (routes to `.vscode/settings.json` or `.code-workspace` file automatically). Extension-managed patterns are tracked in `context.workspaceState` and cleaned up on autoMount change or workspace disable.
+- **`obs://` FileSystemProvider** remains registered for TreeView sidebar, wikilinks, drag-and-drop, and watch events — it does not back a workspace folder.
+- **`FileSearchProvider`/`TextSearchProvider` are proposed (unstable) APIs** as of `@types/vscode@1.118.0`. When stabilized, the extension can switch to a single `obs://` workspace folder with native search, eliminating the `files.exclude` workaround. Check `@types/vscode` for stable availability — do not use while proposed.
+
 ## Documentation
 
-Update the package's README and CONTRIBUTING.md when changes affect user-facing behavior or API surface. Link, don't duplicate.
+Update the package's README and CONTRIBUTING.md when changes affect user-facing behavior or API surface. Link, don't duplicate.

packages/vscode/README.md

@@ -46,26 +46,39 @@ Configure via **Settings UI** or `settings.json`:
 | `obsidianVFS.autoMount` | `string[]` | `[]` | Vault-relative paths (folders or notes) to display in the Explorer tree view on activation |
 | `obsidianVFS.explorer` | `boolean` | `true` | Show the Obsidian VFS tree view in the Explorer sidebar |
 | `obsidianVFS.statusBar` | `boolean` | `true` | Show vault name and mode in the status bar |
-| `obsidianVFS.workspace` | `boolean` | `true` | Add the vault as a workspace folder for Explorer browsing (see below) |
+| `obsidianVFS.workspace` | `boolean` | `true` | Add the vault as a workspace folder for Quick Open and Search (see below) |
 
 All three toggle settings (`explorer`, `statusBar`, `workspace`) take effect immediately — no reload required.
 
 ### Workspace Folder
 
-When `obsidianVFS.workspace` is enabled, the extension adds a single **obs://\<vault\>** workspace folder using the `obs://` virtual file system. Mounted `autoMount` entries appear as children under this root — the Explorer shows one vault entry instead of one per folder. VS Code's **Search** (`Ctrl+Shift+F`) and **Quick Open** (`Cmd+P`) work across mounted content through the `FileSystemProvider`.
+When `obsidianVFS.workspace` is enabled and at least one `autoMount` entry is configured, the extension adds a single `file://` workspace folder at the vault root (named **obs://\<vault\>** in the sidebar). VS Code's **Quick Open** (`Cmd+P`) and **Search** (`Ctrl+Shift+F`) discover vault files through this folder.
 
-All file operations — stat, read, write, directory listing, and file watching — go through the `obs://` provider, which enforces `allowed`/`blocked` security rules from [`.obsidian/obsidian-vfs.json`](../../README.md#vault-configuration) at every level.
+Non-autoMount vault content (`.obsidian/`, `.trash/`, and any directories not in `autoMount`) is hidden from Explorer and Quick Open via `files.exclude` patterns managed by the extension. Your own `files.exclude` patterns are never modified or removed.
 
 **Requirements:**
 
 - At least one local folder must be open — the vault workspace folder is appended to the list to avoid triggering an extension host restart.
+- At least one `autoMount` entry must be configured — the workspace folder is not added when `autoMount` is empty.
 
-**Notes:**
+**How it works:**
 
-- The Explorer tree view and the workspace folder both appear in the sidebar. The tree view provides custom UI (welcome view, context menus), while the workspace folder enables Quick Open and cross-extension visibility. The tree view uses `file://` URIs for opening files, which enables native features like Git integration.
-- `autoMount` entries outside `allowed` or inside `blocked` are filtered from the workspace folder root listing. The core security layer remains as defense-in-depth for navigation into subdirectories.
+- The extension scans the vault root and adds `files.exclude` patterns for entries not in `autoMount`. Patterns are written to workspace settings (`ConfigurationTarget.Workspace`) and tracked internally for cleanup.
+- When `autoMount` entries change, patterns are re-synced automatically — stale patterns are removed and new ones added.
+- When `obsidianVFS.workspace` is disabled, all managed patterns are removed and the workspace folder is deleted.
 - The vault's `.git` repository is automatically added to `git.ignoredRepositories` (user-level setting) when the workspace folder is mounted, preventing VS Code's Git extension from listing it in Source Control. The entry is removed when `obsidianVFS.workspace` is disabled.
 
+**Known limitations:**
+
+- **Pattern scope:** `files.exclude` patterns apply to all workspace folders. If a non-autoMount vault directory shares a name with a directory in your project (e.g., both have a `docs/` folder), the project directory will also be hidden. Fix: add the vault directory to `autoMount`, or rename it in your vault.
+- **Not a security boundary:** `files.exclude` hides content from Explorer and Quick Open but does not enforce access restrictions. The `obs://` FileSystemProvider's path security (`allowed`/`blocked` lists in `.obsidian-vfs.json`) applies to TreeView, wikilink, and drag-and-drop operations.
+- **Title bar:** Adding the vault as a workspace folder creates a multi-root workspace. VS Code may show "UNTITLED (WORKSPACE)" in the title bar.
+
+**Notes:**
+
+- The Explorer tree view and the workspace folder both appear in the sidebar. The tree view provides custom UI (welcome view, context menus, drag-and-drop), while the workspace folder enables Quick Open and full-text search.
+- The `obs://` FileSystemProvider remains registered for the TreeView sidebar, wikilink navigation, and drag-and-drop — it does not back a workspace folder.
+
 ## Related Tools
 
 This VSCode extension provides file-system access and UI integration for Obsidian vaults. If you use **Claude Code**, the companion [`@obsidian-vfs/claude-plugin`](https://github.com/otaviof/obsidian-vfs/tree/main/packages/claude-plugin) enables Claude to read and search your vault via `@obs:` mentions and automatically resolves wikilinks in agent definitions and skills.

packages/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "obsidian-vfs",
   "displayName": "Obsidian VFS",
   "description": "Browse, search, and edit your Obsidian vault directly in VSCode via a virtual file system (obs://)",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "private": true,
   "publisher": "otaviof",
   "engines": {
@@ -127,7 +127,7 @@
         "obsidianVFS.workspace": {
           "type": "boolean",
           "default": true,
-          "description": "Add the vault as a single obs:// workspace folder for Explorer browsing. Mounted entries appear as children under the vault root. Requires at least one local folder open."
+          "description": "Add the vault as a file:// workspace folder for Quick Open (Cmd+P) and Search (Ctrl+Shift+F). Non-autoMount content is hidden via files.exclude patterns managed by the extension. Requires at least one local folder open and at least one autoMount entry."
         }
       }
     }

packages/vscode/src/bootstrap.ts

@@ -2,11 +2,12 @@ import * as vscode from "vscode";
 import { DEFAULT_TIMEOUT_MS, bootstrapTracker, resolveCliPath } from "@obsidian-vfs/core";
 import type { BootstrapResult, VFSResult } from "@obsidian-vfs/core";
 
+import { CONFIG_SECTION } from "./types.js";
 import type { ExtensionConfig } from "./types.js";
 
 /** Read extension configuration from VSCode settings. */
 export function readConfig(): ExtensionConfig {
-  const cfg = vscode.workspace.getConfiguration("obsidianVFS");
+  const cfg = vscode.workspace.getConfiguration(CONFIG_SECTION);
   return {
     cliPath: resolveCliPath({ userPath: cfg.get<string>("cliPath", "") }),
     timeoutMs: cfg.get<number>("timeoutMs", DEFAULT_TIMEOUT_MS),

packages/vscode/src/extension.test.ts

@@ -71,6 +71,8 @@ vi.mock("./workspace-folder.js", async (importOriginal) => {
     hasVaultWorkspaceFolder: vi.fn(),
     excludeVaultFromGitDetection: vi.fn().mockResolvedValue(undefined),
     includeVaultInGitDetection: vi.fn().mockResolvedValue(undefined),
+    syncFilesExclude: vi.fn().mockResolvedValue([]),
+    clearManagedExcludes: vi.fn().mockResolvedValue(undefined),
   };
 });
 
@@ -80,6 +82,7 @@ import type { LocalIndexTracker } from "@obsidian-vfs/core";
 import { bootstrapFromConfig, readConfig } from "./bootstrap.js";
 import { registerCommands } from "./commands.js";
 import { activate, deactivate } from "./extension.js";
+import { CONFIG_KEY } from "./types.js";
 import { SCHEME } from "./uri-adapter.js";
 import { FOLDER_NAME_PREFIX } from "./workspace-folder.js";
 import { ObsidianFileSystemProvider } from "./file-system-provider.js";
@@ -89,10 +92,12 @@ import { VaultTreeDragAndDropController } from "./tree-drag-drop.js";
 import { WikilinkDocumentLinkProvider } from "./wikilink-provider.js";
 import {
   addVaultWorkspaceFolder,
+  clearManagedExcludes,
   excludeVaultFromGitDetection,
   hasVaultWorkspaceFolder,
   includeVaultInGitDetection,
   removeVaultWorkspaceFolders,
+  syncFilesExclude,
 } from "./workspace-folder.js";
 
 const mockBootstrap = vi.mocked(bootstrapFromConfig);
@@ -102,6 +107,8 @@ const mockRemoveWF = vi.mocked(removeVaultWorkspaceFolders);
 const mockHasWF = vi.mocked(hasVaultWorkspaceFolder);
 const mockExcludeGit = vi.mocked(excludeVaultFromGitDetection);
 const mockIncludeGit = vi.mocked(includeVaultInGitDetection);
+const mockSyncExclude = vi.mocked(syncFilesExclude);
+const mockClearExclude = vi.mocked(clearManagedExcludes);
 
 describe("activate", () => {
   beforeEach(() => {
@@ -192,7 +199,7 @@ describe("activate", () => {
     );
   });
 
-  it("adds workspace folder when workspace is true", async () => {
+  it("adds workspace folder and syncs excludes when workspace is true with autoMount", async () => {
     const fakeTracker = {
       context: {
         name: "MyVault",
@@ -214,11 +221,15 @@ describe("activate", () => {
       statusBar: true,
       workspace: true,
     });
+    mockSyncExclude.mockResolvedValueOnce([".obsidian", ".trash"]);
 
-    await activate(fakeContext() as never);
+    const ctx = fakeContext();
+    await activate(ctx as never);
 
-    expect(mockAddWF).toHaveBeenCalledWith("/vault", "MyVault", 1);
+    expect(mockAddWF).toHaveBeenCalledWith("/vault", "MyVault");
     expect(mockExcludeGit).toHaveBeenCalledWith("/vault");
+    expect(mockSyncExclude).toHaveBeenCalledWith("/vault", ["Notes"], [], []);
+    expect(ctx.workspaceState.get("managedFilesExclude")).toEqual([".obsidian", ".trash"]);
   });
 
   it("skips workspace folder when workspace is false", async () => {
@@ -247,6 +258,36 @@ describe("activate", () => {
     await activate(fakeContext() as never);
 
     expect(mockAddWF).not.toHaveBeenCalled();
+    expect(mockSyncExclude).not.toHaveBeenCalled();
+  });
+
+  it("skips workspace folder when autoMount is empty", async () => {
+    const fakeTracker = {
+      context: {
+        name: "MyVault",
+        physicalPath: "/vault",
+        mode: "full",
+        vfsConfig: { agents: [], skills: [], allowed: [], blocked: [] },
+      },
+    } as unknown as LocalIndexTracker;
+
+    mockBootstrap.mockResolvedValueOnce({
+      ok: true,
+      value: { tracker: fakeTracker, initMs: 42 },
+    });
+    mockReadConfig.mockReturnValueOnce({
+      cliPath: "obsidian",
+      timeoutMs: 10_000,
+      autoMount: [],
+      explorer: true,
+      statusBar: true,
+      workspace: true,
+    });
+
+    await activate(fakeContext() as never);
+
+    expect(mockAddWF).not.toHaveBeenCalled();
+    expect(mockSyncExclude).not.toHaveBeenCalled();
   });
 
   it("logs workspace folder result when workspace is true and added", async () => {
@@ -540,7 +581,7 @@ describe("configuration change listener", () => {
       workspace: false,
     });
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.explorer" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.explorer });
 
     const treeProviderInstance = vi.mocked(VaultTreeDataProvider).mock.results[0].value as {
       enabled: boolean;
@@ -582,7 +623,7 @@ describe("configuration change listener", () => {
       workspace: false,
     });
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.explorer" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.explorer });
 
     const treeProviderInstance = vi.mocked(VaultTreeDataProvider).mock.results[0].value as {
       enabled: boolean;
@@ -624,7 +665,7 @@ describe("configuration change listener", () => {
       workspace: false,
     });
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.statusBar" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.statusBar });
 
     const statusBarInstance = vi.mocked(StatusBarManager).mock.results[0].value as {
       show: ReturnType<typeof vi.fn>;
@@ -667,7 +708,7 @@ describe("configuration change listener", () => {
       workspace: false,
     });
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.statusBar" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.statusBar });
 
     const statusBarInstance = vi.mocked(StatusBarManager).mock.results[0].value as {
       show: ReturnType<typeof vi.fn>;
@@ -676,7 +717,7 @@ describe("configuration change listener", () => {
     expect(statusBarInstance.hide).toHaveBeenCalled();
   });
 
-  it("adds workspace folder when workspace config changes to true", async () => {
+  it("adds workspace folder and syncs excludes when workspace config changes to true", async () => {
     const fakeTracker = {
       context: {
         name: "MyVault",
@@ -712,15 +753,18 @@ describe("configuration change listener", () => {
       workspace: true,
     });
     mockAddWF.mockReturnValueOnce({ status: "added" });
+    mockSyncExclude.mockResolvedValueOnce([".obsidian"]);
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.workspace" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.workspace });
+    await new Promise((r) => setTimeout(r, 0));
 
     expect(mockRemoveWF).toHaveBeenCalledWith("/vault");
-    expect(mockAddWF).toHaveBeenCalledWith("/vault", "MyVault", 1);
+    expect(mockAddWF).toHaveBeenCalledWith("/vault", "MyVault");
     expect(mockExcludeGit).toHaveBeenCalledWith("/vault");
+    expect(mockSyncExclude).toHaveBeenCalledWith("/vault", ["Notes"], [], []);
   });
 
-  it("removes workspace folders when workspace config changes to false", async () => {
+  it("clears excludes and removes workspace folders when workspace config changes to false", async () => {
     const fakeTracker = {
       context: {
         name: "MyVault",
@@ -756,14 +800,16 @@ describe("configuration change listener", () => {
       workspace: false,
     });
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.workspace" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.workspace });
+    await new Promise((r) => setTimeout(r, 0));
 
     expect(mockRemoveWF).toHaveBeenCalledWith("/vault");
     expect(mockAddWF).not.toHaveBeenCalled();
+    expect(mockClearExclude).toHaveBeenCalledWith([]);
     expect(mockIncludeGit).toHaveBeenCalledWith("/vault");
   });
 
-  it("updates provider without removing workspace folder when autoMount changes", async () => {
+  it("syncs excludes when autoMount changes without workspace toggle", async () => {
     const fakeTracker = {
       context: {
         name: "MyVault",
@@ -803,12 +849,15 @@ describe("configuration change listener", () => {
       statusBar: true,
       workspace: true,
     });
+    mockSyncExclude.mockResolvedValueOnce([".obsidian"]);
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.autoMount" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.autoMount });
+    await new Promise((r) => setTimeout(r, 0));
 
     expect(providerInstance.setAutoMount).toHaveBeenCalledWith(["Notes", "Projects"]);
     expect(mockRemoveWF).not.toHaveBeenCalled();
     expect(mockAddWF).not.toHaveBeenCalled();
+    expect(mockSyncExclude).toHaveBeenCalledWith("/vault", ["Notes", "Projects"], [], []);
   });
 
   it("adds workspace folder when autoMount goes from empty to non-empty", async () => {
@@ -840,6 +889,7 @@ describe("configuration change listener", () => {
 
     mockHasWF.mockReturnValueOnce(false);
     mockAddWF.mockReturnValueOnce({ status: "added" });
+    mockSyncExclude.mockResolvedValueOnce([".obsidian"]);
     mockReadConfig.mockReturnValueOnce({
       cliPath: "obsidian",
       timeoutMs: 10_000,
@@ -849,14 +899,16 @@ describe("configuration change listener", () => {
       workspace: true,
     });
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.autoMount" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.autoMount });
+    await new Promise((r) => setTimeout(r, 0));
 
-    expect(mockAddWF).toHaveBeenCalledWith("/vault", "MyVault", 1);
+    expect(mockAddWF).toHaveBeenCalledWith("/vault", "MyVault");
     expect(mockExcludeGit).toHaveBeenCalledWith("/vault");
+    expect(mockSyncExclude).toHaveBeenCalledWith("/vault", ["Notes"], [], []);
     expect(mockRemoveWF).not.toHaveBeenCalled();
   });
 
-  it("removes workspace folder when autoMount becomes empty", async () => {
+  it("removes workspace folder and clears excludes when autoMount becomes empty", async () => {
     const fakeTracker = {
       context: {
         name: "MyVault",
@@ -892,9 +944,11 @@ describe("configuration change listener", () => {
       workspace: true,
     });
 
-    configChangeListener!({ affectsConfiguration: (key) => key === "obsidianVFS.autoMount" });
+    configChangeListener!({ affectsConfiguration: (key) => key === CONFIG_KEY.autoMount });
+    await new Promise((r) => setTimeout(r, 0));
 
     expect(mockRemoveWF).toHaveBeenCalledWith("/vault");
+    expect(mockClearExclude).toHaveBeenCalledWith([]);
     expect(mockAddWF).not.toHaveBeenCalled();
   });
 });