feat(core): depth-limited vault enumeration with listFolders

Add a shared BFS walker (walkVault) to core that both listMarkdownFiles
and the new listFolders use. A configurable depthLimit (0 = unlimited)
controls how many directory levels are traversed. The VSCode extension
reads the limit from the new obsidianVFS.depthLimit setting (default 4,
single source of truth in package.json) and passes it to Mount Folder,
Mount Note, and Search Notes commands.

Also replaces ~53 bare error-code string literals across 15 core files
with ERR.* and ERRNO.* constants from types.ts; ErrorCode is now
derived from the ERR object so new codes only need one addition.

Versions: core/cli 0.2.1 → 0.3.0, vscode 0.3.2 → 0.3.3.

Assisted-by: Claude

Author: otaviof

packages/claude-plugin/bundle/entry-expansion.mjs

@@ -1,6 +1,6 @@
 {
   "name": "@obsidian-vfs/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "CLI for Obsidian VFS — provision skills/agents, inspect vault resources",
   "license": "Apache-2.0",

packages/claude-plugin/bundle/entry-subagent.mjs

@@ -38,7 +38,7 @@ The `./testing` entry point provides test doubles for consumer packages:
 | Category | Symbols |
 |----------|---------|
 | Resolution | `resolveMention`, `resolveSkillMention`, `resolveWikilink`, `normalizeMention`, `parseSection` |
-| File I/O | `readVirtualFile`, `listMarkdownFiles`, `readDirectory` |
+| File I/O | `readVirtualFile`, `listMarkdownFiles`, `listFolders`, `readDirectory` |
 | CLI | `ObsidianCLI`, `resolveExecConfig`, `resolveCliPath` |
 | Content | `sliceContent`, `scrubWikilinks`, `processContent`, `resolveEmbeds`, `maskCodeRegions` |
 | Frontmatter | `extractFrontmatter`, `extractCuratedFrontmatter`, `remapModelLine`, `mapModelToClaude` |

packages/claude-plugin/bundle/hook-handler.mjs

@@ -1,6 +1,6 @@
 {
   "name": "@obsidian-vfs/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Core library for Obsidian VFS — vault resolution, content processing, path security",
   "license": "Apache-2.0",

packages/cli/package.json

@@ -1,4 +1,5 @@
 import { buildObsUri } from "./uri.js";
+import { ERR } from "./types.js";
 import type { VFSResult } from "./types.js";
 
 /**
@@ -46,7 +47,7 @@ export function sliceContent(markdown: string, heading: string): VFSResult<strin
 
   return {
     ok: false,
-    error: { code: "FILE_NOT_FOUND", message: `Section not found: ${heading}` },
+    error: { code: ERR.FILE_NOT_FOUND, message: `Section not found: ${heading}` },
   };
 }
 
@@ -79,7 +80,7 @@ export function processContent(markdown: string, options: ContentSliceOptions):
     if (options.vaultName === undefined) {
       return {
         ok: false,
-        error: { code: "INVALID_URI", message: "vaultName is required when scrubbing wikilinks" },
+        error: { code: ERR.INVALID_URI, message: "vaultName is required when scrubbing wikilinks" },
       };
     }
     result = scrubWikilinks(result, options.vaultName);

packages/core/README.md

@@ -1,6 +1,7 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 
+import { ERR, ERRNO } from "./types.js";
 import type { VFSResult } from "./types.js";
 import { resolveCliPath } from "./resolve-cli-path.js";
 
@@ -61,20 +62,24 @@ export async function execCLI(
     if (err instanceof Error && err.name === "AbortError") {
       return {
         ok: false,
-        error: { code: "TIMEOUT", message: `CLI timed out after ${options.timeoutMs}ms` },
+        error: { code: ERR.TIMEOUT, message: `CLI timed out after ${options.timeoutMs}ms` },
       };
     }
-    if (err instanceof Error && "code" in err && (err as NodeJS.ErrnoException).code === "ENOENT") {
+    if (
+      err instanceof Error &&
+      "code" in err &&
+      (err as NodeJS.ErrnoException).code === ERRNO.ENOENT
+    ) {
       return {
         ok: false,
         error: {
-          code: "CLI_UNAVAILABLE",
+          code: ERR.CLI_UNAVAILABLE,
           message: `CLI binary not found: ${options.cliPath}`,
         },
       };
     }
     const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, error: { code: "CLI_ERROR", message } };
+    return { ok: false, error: { code: ERR.CLI_ERROR, message } };
   } finally {
     clearTimeout(timer);
   }

packages/core/package.json

@@ -1,8 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { Dirent } from "node:fs";
 
-import { listMarkdownFiles, readDirectory, statVirtualFile } from "./fs-enumeration.js";
-import { mockFsFunction } from "./test-helpers.js";
+import { listFolders, listMarkdownFiles, readDirectory, statVirtualFile } from "./fs-enumeration.js";
+import { makeDirent, mockFsFunction } from "./test-helpers.js";
 
 vi.mock("node:fs/promises", () => ({
   readdir: vi.fn(),
@@ -17,21 +16,6 @@ const realpathMock = mockFsFunction(realpath);
 
 const OPTIONS = { vaultRoot: "/vault", allowed: [] as string[], blocked: [] as string[] };
 
-function makeDirent(name: string, isDir: boolean): Dirent {
-  return {
-    name,
-    isDirectory: () => isDir,
-    isFile: () => !isDir,
-    isBlockDevice: () => false,
-    isCharacterDevice: () => false,
-    isFIFO: () => false,
-    isSocket: () => false,
-    isSymbolicLink: () => false,
-    parentPath: "/vault",
-    path: "/vault",
-  };
-}
-
 describe("readDirectory", () => {
   beforeEach(() => {
     vi.resetAllMocks();
@@ -142,20 +126,29 @@ describe("listMarkdownFiles", () => {
   });
 
   it("enumerates markdown files sorted alphabetically", async () => {
-    readdirMock.mockResolvedValueOnce(["b-note.md", "a-note.md", "image.png"]);
+    readdirMock.mockResolvedValueOnce([
+      makeDirent("b-note.md", false),
+      makeDirent("a-note.md", false),
+      makeDirent("image.png", false),
+    ]);
     const result = await listMarkdownFiles(OPTIONS);
     expect(result).toEqual({ ok: true, value: ["a-note.md", "b-note.md"] });
   });
 
   it("skips entries with dot-prefixed path segments", async () => {
-    readdirMock.mockResolvedValueOnce([".obsidian/plugins/note.md", "visible.md"]);
+    readdirMock.mockResolvedValueOnce([
+      makeDirent(".obsidian", true),
+      makeDirent("visible.md", false),
+    ]);
     const result = await listMarkdownFiles(OPTIONS);
     expect(result).toEqual({ ok: true, value: ["visible.md"] });
   });
 
   it("searches only allowed when specified", async () => {
     const options = { ...OPTIONS, allowed: ["notes", "docs"] };
-    readdirMock.mockResolvedValueOnce(["intro.md"]).mockResolvedValueOnce(["guide.md"]);
+    readdirMock
+      .mockResolvedValueOnce([makeDirent("intro.md", false)])
+      .mockResolvedValueOnce([makeDirent("guide.md", false)]);
     const result = await listMarkdownFiles(options);
     expect(result).toEqual({
       ok: true,
@@ -171,30 +164,167 @@ describe("listMarkdownFiles", () => {
 
   it("skips unreadable directories", async () => {
     const options = { ...OPTIONS, allowed: ["bad", "good"] };
-    readdirMock.mockRejectedValueOnce(new Error("ENOENT")).mockResolvedValueOnce(["note.md"]);
+    readdirMock
+      .mockRejectedValueOnce(new Error("ENOENT"))
+      .mockResolvedValueOnce([makeDirent("note.md", false)]);
     const result = await listMarkdownFiles(options);
     expect(result).toEqual({ ok: true, value: ["good/note.md"] });
   });
 
   it("handles nested subdirectories", async () => {
-    readdirMock.mockResolvedValueOnce(["sub/deep/note.md", "top.md"]);
+    readdirMock
+      .mockResolvedValueOnce([makeDirent("sub", true), makeDirent("top.md", false)])
+      .mockResolvedValueOnce([makeDirent("deep", true)])
+      .mockResolvedValueOnce([makeDirent("note.md", false)]);
     const result = await listMarkdownFiles(OPTIONS);
     expect(result).toEqual({ ok: true, value: ["sub/deep/note.md", "top.md"] });
   });
 
   it("excludes files in blocked folders", async () => {
     const options = { ...OPTIONS, allowed: ["notes"], blocked: ["notes/draft"] };
-    readdirMock.mockResolvedValueOnce(["public/doc.md", "draft/wip.md"]);
+    readdirMock
+      .mockResolvedValueOnce([makeDirent("public", true), makeDirent("draft", true)])
+      .mockResolvedValueOnce([makeDirent("doc.md", false)]);
     const result = await listMarkdownFiles(options);
     expect(result).toEqual({ ok: true, value: ["notes/public/doc.md"] });
   });
 
   it("excludes blocked files without allowed", async () => {
     const options = { ...OPTIONS, blocked: ["private"] };
-    readdirMock.mockResolvedValueOnce(["notes/doc.md", "private/secret.md"]);
+    readdirMock
+      .mockResolvedValueOnce([makeDirent("notes", true), makeDirent("private", true)])
+      .mockResolvedValueOnce([makeDirent("doc.md", false)]);
     const result = await listMarkdownFiles(options);
     expect(result).toEqual({ ok: true, value: ["notes/doc.md"] });
   });
+
+  it("respects depthLimit parameter", async () => {
+    readdirMock
+      .mockResolvedValueOnce([makeDirent("sub", true), makeDirent("top.md", false)])
+      .mockResolvedValueOnce([makeDirent("deep", true), makeDirent("mid.md", false)])
+      .mockResolvedValueOnce([makeDirent("bottom.md", false)]);
+    const result = await listMarkdownFiles(OPTIONS, 2);
+    expect(result).toEqual({ ok: true, value: ["sub/mid.md", "top.md"] });
+  });
+
+  it("treats depthLimit 0 as unlimited", async () => {
+    readdirMock
+      .mockResolvedValueOnce([makeDirent("sub", true)])
+      .mockResolvedValueOnce([makeDirent("deep", true)])
+      .mockResolvedValueOnce([makeDirent("note.md", false)]);
+    const result = await listMarkdownFiles(OPTIONS, 0);
+    expect(result).toEqual({ ok: true, value: ["sub/deep/note.md"] });
+  });
+});
+
+describe("listFolders", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it("enumerates folders recursively up to depthLimit", async () => {
+    readdirMock
+      .mockResolvedValueOnce([
+        makeDirent("10-projects", true),
+        makeDirent("20-areas", true),
+        makeDirent("note.md", false),
+      ])
+      .mockResolvedValueOnce([makeDirent("active", true), makeDirent("archive", true)])
+      .mockResolvedValueOnce([]);
+    const result = await listFolders(OPTIONS, 2);
+    expect(result).toEqual({
+      ok: true,
+      value: ["10-projects", "10-projects/active", "10-projects/archive", "20-areas"],
+    });
+  });
+
+  it("depth 1 returns only top-level folders", async () => {
+    readdirMock.mockResolvedValueOnce([
+      makeDirent("10-projects", true),
+      makeDirent("20-areas", true),
+      makeDirent("note.md", false),
+    ]);
+    const result = await listFolders(OPTIONS, 1);
+    expect(result).toEqual({
+      ok: true,
+      value: ["10-projects", "20-areas"],
+    });
+  });
+
+  it("depth 0 returns unlimited (all folders)", async () => {
+    readdirMock
+      .mockResolvedValueOnce([makeDirent("a", true)])
+      .mockResolvedValueOnce([makeDirent("b", true)])
+      .mockResolvedValueOnce([makeDirent("c", true)])
+      .mockResolvedValueOnce([]);
+    const result = await listFolders(OPTIONS, 0);
+    expect(result).toEqual({
+      ok: true,
+      value: ["a", "a/b", "a/b/c"],
+    });
+  });
+
+  it("filters dot-prefixed directories", async () => {
+    readdirMock.mockResolvedValueOnce([
+      makeDirent(".obsidian", true),
+      makeDirent(".git", true),
+      makeDirent("notes", true),
+    ]);
+    const result = await listFolders(OPTIONS, 1);
+    expect(result).toEqual({ ok: true, value: ["notes"] });
+  });
+
+  it("enforces allowed list", async () => {
+    const options = { ...OPTIONS, allowed: ["notes"] };
+    readdirMock.mockResolvedValueOnce([makeDirent("sub", true)]).mockResolvedValueOnce([]);
+    const result = await listFolders(options, 2);
+    expect(result).toEqual({ ok: true, value: ["notes", "notes/sub"] });
+  });
+
+  it("includes allowed roots themselves", async () => {
+    const options = { ...OPTIONS, allowed: ["10-projects", "20-areas"] };
+    readdirMock
+      .mockResolvedValueOnce([makeDirent("calunga", true)])
+      .mockResolvedValueOnce([makeDirent("career", true)]);
+    const result = await listFolders(options, 1);
+    expect(result).toEqual({
+      ok: true,
+      value: ["10-projects", "10-projects/calunga", "20-areas", "20-areas/career"],
+    });
+  });
+
+  it("enforces blocked list", async () => {
+    const options = { ...OPTIONS, blocked: ["private"] };
+    readdirMock.mockResolvedValueOnce([makeDirent("notes", true), makeDirent("private", true)]);
+    const result = await listFolders(options, 1);
+    expect(result).toEqual({ ok: true, value: ["notes"] });
+  });
+
+  it("skips unreadable directories", async () => {
+    const options = { ...OPTIONS, allowed: ["bad", "good"] };
+    readdirMock
+      .mockRejectedValueOnce(new Error("ENOENT"))
+      .mockResolvedValueOnce([makeDirent("sub", true)])
+      .mockResolvedValueOnce([]);
+    const result = await listFolders(options, 2);
+    expect(result).toEqual({ ok: true, value: ["bad", "good", "good/sub"] });
+  });
+
+  it("returns empty array for empty vault", async () => {
+    readdirMock.mockResolvedValueOnce([]);
+    const result = await listFolders(OPTIONS, 1);
+    expect(result).toEqual({ ok: true, value: [] });
+  });
+
+  it("returns sorted results", async () => {
+    readdirMock.mockResolvedValueOnce([
+      makeDirent("zebra", true),
+      makeDirent("alpha", true),
+      makeDirent("mid", true),
+    ]);
+    const result = await listFolders(OPTIONS, 1);
+    expect(result).toEqual({ ok: true, value: ["alpha", "mid", "zebra"] });
+  });
 });
 
 describe("statVirtualFile", () => {