mulmoclaude 1.2.0 → 1.3.0

package/server/api/routes/collections.ts

@@ -12,6 +12,7 @@ import { Router, Request, Response, NextFunction } from "express";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 import { actionVisible } from "@mulmoclaude/core/collection";
 import {
+  collectionWritable,
   computeCollectionIcon,
   discoverCollections,
   generateItemId,
@@ -19,16 +20,16 @@ import {
   deleteCollectionRefusalMessage,
   deleteCustomView,
   deleteItem,
-  listItems,
   loadCollection,
-  readItem,
   readSkillTemplate,
   readCustomViewHtml,
   readCustomViewI18n,
+  readOnlyRefusal,
   buildActionSeedPrompt,
   buildCollectionActionSeedPrompt,
   promptPathsFor,
   resolveCreateItemId,
+  storeFor,
   toDetail,
   toSummary,
   applyMutateAction,
@@ -57,7 +58,7 @@ import {
   type RemoteViewItemsResult,
 } from "../../workspace/collections/remoteView.js";
 import { clampLimit, clampOffset, normalizeFields, normalizeMutate } from "@mulmoclaude/core/remote-view";
-import { badRequest, notFound, conflict, forbidden, serverError, serviceUnavailable } from "../../utils/httpError.js";
+import { badRequest, notFound, conflict, forbidden, methodNotAllowed, serverError, serviceUnavailable } from "../../utils/httpError.js";
 import { ONE_MINUTE_MS } from "../../utils/time.js";
 import { errorMessage } from "../../utils/errors.js";
 import { log } from "../../system/logger/index.js";
@@ -69,6 +70,34 @@ import { clampCapabilities, mintViewToken, requireViewToken, type ViewCapability
 
 const router = Router();
 
+// Load a collection by slug or send a 404 and return null. Callers do
+// `const collection = await loadCollectionOr404(slug, res); if (!collection) return;`.
+// The load-or-404 preamble was repeated across ~16 route handlers.
+async function loadCollectionOr404(slug: string, res: Response): Promise<LoadedCollection | null> {
+  const collection = await loadCollection(slug);
+  if (!collection) {
+    notFound(res, `collection '${slug}' not found`);
+    return null;
+  }
+  return collection;
+}
+
+type CustomView = NonNullable<LoadedCollection["schema"]["views"]>[number];
+
+// Resolve a collection + one of its custom views by id, or send a 404
+// (missing collection or missing view) and return null. Shared by the
+// view-file / view-i18n / view-token routes.
+async function resolveCustomViewOr404(slug: string, viewId: string, res: Response): Promise<{ collection: LoadedCollection; view: CustomView } | null> {
+  const collection = await loadCollectionOr404(slug, res);
+  if (!collection) return null;
+  const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
+  if (!view) {
+    notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
+    return null;
+  }
+  return { collection, view };
+}
+
 interface CollectionsListResponse {
   collections: CollectionSummary[];
 }
@@ -156,13 +185,10 @@ router.get(API_ROUTES.collections.list, async (_req: Request, res: Response<Coll
 });
 
 router.get(API_ROUTES.collections.detail, async (req: Request<{ slug: string }>, res: Response<CollectionDetailResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   try {
-    const items = await listItems(collection.dataDir);
+    const items = await storeFor(collection).list();
     // Best-effort validation: a malformed record is silently skipped at
     // read time, so surface the problems here too (the same pass
     // presentCollection runs) and let the view offer a Repair button.
@@ -193,11 +219,8 @@ router.get(API_ROUTES.collections.detail, async (req: Request<{ slug: string }>,
 // non-preset collections are deletable; see deleteCollection for the
 // scope rules and the archive layout.
 router.delete(API_ROUTES.collections.detail, async (req: Request<{ slug: string }>, res: Response<DeleteCollectionResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   try {
     const result = await deleteCollection(collection);
     if (result.kind !== "ok") {
@@ -218,9 +241,10 @@ function extractRecord(body: unknown): CollectionItem | null {
 }
 
 router.post(API_ROUTES.collections.items, async (req: Request<{ slug: string }>, res: Response<ItemMutationResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
+  if (!collectionWritable(collection)) {
+    methodNotAllowed(res, readOnlyRefusal(collection.slug));
     return;
   }
   const record = extractRecord(req.body);
@@ -260,9 +284,10 @@ router.post(API_ROUTES.collections.items, async (req: Request<{ slug: string }>,
 });
 
 router.put(API_ROUTES.collections.item, async (req: Request<{ slug: string; itemId: string }>, res: Response<ItemMutationResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
+  if (!collectionWritable(collection)) {
+    methodNotAllowed(res, readOnlyRefusal(collection.slug));
     return;
   }
   const record = extractRecord(req.body);
@@ -306,9 +331,10 @@ router.put(API_ROUTES.collections.item, async (req: Request<{ slug: string; item
 });
 
 router.delete(API_ROUTES.collections.item, async (req: Request<{ slug: string; itemId: string }>, res: Response<DeleteResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
+  if (!collectionWritable(collection)) {
+    methodNotAllowed(res, readOnlyRefusal(collection.slug));
     return;
   }
   try {
@@ -351,11 +377,8 @@ interface RefreshResponse {
 // carries no `ingest` block (it's an ordinary skill collection, not a
 // feed). Backs the CollectionView "Refresh feed" button.
 router.post(API_ROUTES.collections.refresh, async (req: Request<{ slug: string }>, res: Response<RefreshResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   if (!collection.schema.ingest) {
     badRequest(res, `collection '${collection.slug}' is not a feed (no ingest config)`);
     return;
@@ -441,18 +464,15 @@ async function respondForMutateAction(
 // the hidden worker itself; for `kind: "mutate"`, it applies the
 // declarative write). No domain (invoice / PDF / role) literals.
 router.post(API_ROUTES.collections.itemAction, async (req: Request<{ slug: string; itemId: string; actionId: string }>, res: Response<ActionRunResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   const action = collection.schema.actions?.find((entry) => entry.id === req.params.actionId);
   if (!action) {
     notFound(res, `action '${req.params.actionId}' not found on collection '${collection.slug}'`);
     return;
   }
   try {
-    const record = await readItem(collection.dataDir, req.params.itemId);
+    const record = await storeFor(collection).read(req.params.itemId);
     if (!record) {
       notFound(res, `item '${req.params.itemId}' not found`);
       return;
@@ -469,6 +489,12 @@ router.post(API_ROUTES.collections.itemAction, async (req: Request<{ slug: strin
     // the declarative write itself (require was just enforced above,
     // same visibility-is-authorization rule as the seeded kinds).
     if (action.kind === "mutate") {
+      // Schema validation already rejects mutate actions on a dataSource
+      // collection; this is the defensive server-side twin.
+      if (!collectionWritable(collection)) {
+        methodNotAllowed(res, readOnlyRefusal(collection.slug));
+        return;
+      }
       await respondForMutateAction(res, collection, action, req.params.itemId, req.body as { params?: unknown } | undefined);
       return;
     }
@@ -498,7 +524,7 @@ router.post(API_ROUTES.collections.itemAction, async (req: Request<{ slug: strin
 async function buildCollectionActionSeed(collection: LoadedCollection, action: CollectionSeededAction): Promise<ActionSeedResponse | null> {
   const template = await readSkillTemplate(collection.skillDir, action.template);
   if (template === null) return null;
-  const items = await listItems(collection.dataDir);
+  const items = await storeFor(collection).list();
   log.info("collections", "collection action seed built", { slug: collection.slug, actionId: action.id, items: items.length });
   return { prompt: buildCollectionActionSeedPrompt(items, collection.schema, template, promptPathsFor(collection, workspacePath)), role: action.role };
 }
@@ -506,11 +532,8 @@ async function buildCollectionActionSeed(collection: LoadedCollection, action: C
 // Like the per-record route but with no `itemId`: there is no record to read or
 // gate on, so the seed injects a progress summary instead. No domain literals.
 router.post(API_ROUTES.collections.collectionAction, async (req: Request<{ slug: string; actionId: string }>, res: Response<ActionRunResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   const action = collection.schema.collectionActions?.find((entry) => entry.id === req.params.actionId);
   if (!action) {
     notFound(res, `collection action '${req.params.actionId}' not found on collection '${collection.slug}'`);
@@ -628,16 +651,9 @@ router.get(API_ROUTES.collections.viewFile, async (req: Request<{ slug: string }
   try {
     const { slug } = req.params;
     const viewId = typeof req.query.id === "string" ? req.query.id : "";
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
-    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
-    if (!view) {
-      notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
-      return;
-    }
+    const resolved = await resolveCustomViewOr404(slug, viewId, res);
+    if (!resolved) return;
+    const { collection, view } = resolved;
     // Path-safe, source-aware read through the collections domain layer (no raw
     // fs / hardcoded subpaths in the route).
     const html = await readCustomViewHtml(collection, view.file);
@@ -670,11 +686,8 @@ router.get(API_ROUTES.collections.remoteView, async (req: Request<{ slug: string
     const { slug } = req.params;
     const viewId = typeof req.query.id === "string" ? req.query.id : "";
     const locale = typeof req.query.locale === "string" ? req.query.locale : "";
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
+    const collection = await loadCollectionOr404(slug, res);
+    if (!collection) return;
     const result = await buildRemoteView(collection, viewId, locale);
     if (result.kind !== "ok") {
       sendRemoteViewFailure(res, result, slug);
@@ -692,6 +705,7 @@ router.get(API_ROUTES.collections.remoteView, async (req: Request<{ slug: string
 function sendMutateRemoteViewFailure(res: Response, result: Exclude<MutateRemoteViewResult, { kind: "ok" }>, slug: string): void {
   const message = mutateRemoteViewFailureMessage(result, slug);
   if (result.kind === "view-not-found" || result.kind === "item-not-found") notFound(res, message);
+  else if (result.kind === "read-only-collection") methodNotAllowed(res, message);
   else if (result.kind === "not-writable" || result.kind === "delete-not-allowed" || result.kind === "field-not-editable" || result.kind === "path-escape")
     forbidden(res, message);
   else badRequest(res, message);
@@ -710,11 +724,8 @@ router.post(API_ROUTES.collections.remoteViewMutate, async (req: Request<{ slug:
       badRequest(res, "invalid mutate request — expected { op: 'update'|'delete', id, patch? }");
       return;
     }
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
+    const collection = await loadCollectionOr404(slug, res);
+    if (!collection) return;
     const result = await mutateRemoteView(collection, viewId, request);
     if (result.kind !== "ok") {
       sendMutateRemoteViewFailure(res, result, slug);
@@ -753,11 +764,8 @@ router.get(API_ROUTES.collections.remoteViewItems, async (req: Request<{ slug: s
   try {
     const { slug, viewId } = req.params;
     const request = { offset: clampOffset(req.query.offset), limit: clampLimit(req.query.limit), fields: normalizeFields(csvParam(req.query.fields)) };
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
+    const collection = await loadCollectionOr404(slug, res);
+    if (!collection) return;
     const result = await remoteViewItems(collection, viewId, request);
     if (result.kind !== "ok") {
       sendRemoteViewItemsFailure(res, result, slug);
@@ -788,16 +796,9 @@ router.get(API_ROUTES.collections.viewI18n, async (req: Request<{ slug: string }
     const { slug } = req.params;
     const viewId = typeof req.query.id === "string" ? req.query.id : "";
     const locale = typeof req.query.locale === "string" ? req.query.locale : "";
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
-    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
-    if (!view) {
-      notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
-      return;
-    }
+    const resolved = await resolveCustomViewOr404(slug, viewId, res);
+    if (!resolved) return;
+    const { collection, view } = resolved;
     if (!view.i18n) {
       // The view declared no translation file — return the empty contract so
       // the client doesn't have to special-case "no i18n" with a different
@@ -829,16 +830,9 @@ router.post(API_ROUTES.collections.viewToken, async (req: Request<{ slug: string
       badRequest(res, "`viewId` is required");
       return;
     }
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
-    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
-    if (!view) {
-      notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
-      return;
-    }
+    const resolved = await resolveCustomViewOr404(slug, viewId, res);
+    if (!resolved) return;
+    const { view } = resolved;
     const granted = clampCapabilities(view.capabilities, parseCapabilities(body.capabilities));
     const minted = mintViewToken(slug, granted);
     if (!minted) {
@@ -871,6 +865,72 @@ router.get(API_ROUTES.collections.viewData, viewDataCors, requireViewToken("read
   }
 });
 
+// Preflight for the token-scoped query endpoint (POST + JSON from a
+// sandboxed opaque-origin iframe — same CORS story as view-data itself).
+router.options(API_ROUTES.collections.viewDataQuery, viewDataCors, (_req: Request, res: Response) => {
+  res.sendStatus(204);
+});
+
+/** Per-slug in-flight cap for view-issued aggregation queries. The
+ *  per-minute limiter alone still lets a burst arrive CONCURRENTLY —
+ *  each query is a full-file DuckDB scan, so a runaway dashboard loop
+ *  could otherwise stack dozens of scans at once. Exported factory so
+ *  the unit test can drive the counter without HTTP. */
+export function makeViewQueryConcurrencyGuard(max: number) {
+  const inflight = new Map<string, number>();
+  return (req: Request<{ slug?: string }>, res: Response, next: NextFunction): void => {
+    const slug = req.params.slug ?? "";
+    const current = inflight.get(slug) ?? 0;
+    if (current >= max) {
+      res.status(429).json({ error: "too many concurrent queries for this collection — retry shortly" });
+      return;
+    }
+    inflight.set(slug, current + 1);
+    let released = false;
+    // `close` fires after the response finishes OR the client disconnects
+    // mid-request — either way the scan slot must come back exactly once.
+    res.once("close", () => {
+      if (released) return;
+      released = true;
+      const now = inflight.get(slug) ?? 1;
+      if (now <= 1) inflight.delete(slug);
+      else inflight.set(slug, now - 1);
+    });
+    next();
+  };
+}
+
+const VIEW_QUERY_MAX_CONCURRENT = 4;
+const viewQueryConcurrency = makeViewQueryConcurrencyGuard(VIEW_QUERY_MAX_CONCURRENT);
+
+// Scoped aggregation: run a structured query (the DSL — never raw SQL)
+// over a dataSource collection's whole data file. Read capability only:
+// the DSL is read-only by construction. Reuses the manageCollection
+// handler so a view can never do more than the agent's own queryItems
+// (same validation, same file-backed refusal). Guarded twice: the
+// per-minute limiter (request volume) + the in-flight cap (concurrent
+// full-file scans).
+router.post(
+  API_ROUTES.collections.viewDataQuery,
+  viewDataCors,
+  viewActionRateLimit,
+  viewQueryConcurrency,
+  requireViewToken("read"),
+  async (req: Request<{ slug: string }>, res: Response) => {
+    try {
+      const body = (req.body ?? {}) as { query?: unknown };
+      const raw = await manageCollection.handler({ action: "queryItems", slug: req.params.slug, query: body.query });
+      sendToolResult(res, raw);
+    } catch (err) {
+      // Log the detail server-side; the token holder gets a FIXED message —
+      // a raw DuckDB error can carry absolute paths / host internals, and a
+      // scoped view is not a trusted audience for those.
+      log.warn("collections", "view-data query failed", { slug: req.params.slug.replace(/[\r\n]/g, " "), error: errorMessage(err) });
+      serverError(res, "collection query failed");
+    }
+  },
+);
+
 // Scoped write: validated putItems. Requires the `write` capability.
 router.put(API_ROUTES.collections.viewData, viewDataCors, requireViewToken("write"), async (req: Request<{ slug: string }>, res: Response) => {
   try {
@@ -903,11 +963,8 @@ router.post(
   requireViewToken("write"),
   async (req: Request<{ slug: string; actionId: string }>, res: Response<ActionRunResponse>) => {
     try {
-      const collection = await loadCollection(req.params.slug);
-      if (!collection) {
-        notFound(res, `collection '${req.params.slug}' not found`);
-        return;
-      }
+      const collection = await loadCollectionOr404(req.params.slug, res);
+      if (!collection) return;
       const action = collection.schema.actions?.find((entry) => entry.id === req.params.actionId);
       if (!action) {
         notFound(res, `action '${req.params.actionId}' not found on collection '${collection.slug}'`);
@@ -923,7 +980,7 @@ router.post(
         badRequest(res, "`itemId` is required (the record's primary-key value)");
         return;
       }
-      const record = await readItem(collection.dataDir, itemId);
+      const record = await storeFor(collection).read(itemId);
       if (!record) {
         notFound(res, `item '${itemId}' not found`);
         return;
@@ -971,11 +1028,8 @@ function sendDeleteViewRefusal(res: Response, result: Exclude<DeleteViewResult,
 // refuses user-scope + preset collections, consistent with collection delete.
 router.delete(API_ROUTES.collections.viewDelete, async (req: Request<{ slug: string; viewId: string }>, res: Response<DeleteViewResponse>) => {
   try {
-    const collection = await loadCollection(req.params.slug);
-    if (!collection) {
-      notFound(res, `collection '${req.params.slug}' not found`);
-      return;
-    }
+    const collection = await loadCollectionOr404(req.params.slug, res);
+    if (!collection) return;
     const result = await deleteCustomView(collection, req.params.viewId);
     if (result.kind !== "ok") {
       sendDeleteViewRefusal(res, result);

package/server/api/routes/files.ts

@@ -452,6 +452,53 @@ function pipeWithErrorHandling(stream: ReadStream, res: Response<ErrorResponse>)
   stream.pipe(res);
 }
 
+// Apply the UI-visibility filters (hidden dirs, sensitive files,
+// symlinks, .gitignore matches) to a single directory entry and stat
+// it. Returns the resolved child paths + stat, or null when the entry
+// should not surface. The recursive walk and the shallow lazy-expand
+// path share this so the filter policy lives in exactly one place.
+async function resolveVisibleChild(
+  entry: Dirent,
+  absPath: string,
+  relPath: string,
+  localFilter: GitignoreFilter | undefined,
+): Promise<{ childRel: string; childAbs: string; childStat: Stats } | null> {
+  if (HIDDEN_DIRS.has(entry.name)) return null;
+  if (!entry.isDirectory() && isSensitivePath(entry.name)) return null;
+  if (entry.isSymbolicLink()) return null;
+  const childRel = relPath ? path.join(relPath, entry.name) : entry.name;
+  // .gitignore check: for directories, append trailing / so
+  // directory-only patterns (e.g. "node_modules/") match.
+  if (localFilter) {
+    const testPath = entry.isDirectory() ? `${childRel}/` : childRel;
+    if (localFilter.ignores(testPath)) return null;
+  }
+  const childAbs = path.join(absPath, entry.name);
+  const childStat = await statSafeAsync(childAbs);
+  if (!childStat) return null;
+  return { childRel, childAbs, childStat };
+}
+
+// Await a directory's child-node promises, drop the filtered-out nulls,
+// sort (dirs before files, alphabetical within type), and wrap them in
+// the parent's `dir` TreeNode. Shared by the recursive and shallow
+// builders so the assembly + ordering is defined once.
+async function assembleDirNode(childPromises: Promise<TreeNode | null>[], relPath: string, modifiedMs: number): Promise<TreeNode> {
+  const resolved = await Promise.all(childPromises);
+  const children = resolved.filter((childNode): childNode is TreeNode => childNode !== null);
+  children.sort((leftChild, rightChild) => {
+    if (leftChild.type !== rightChild.type) return leftChild.type === "dir" ? -1 : 1;
+    return leftChild.name.localeCompare(rightChild.name);
+  });
+  return {
+    name: relPath ? path.basename(relPath) : "",
+    path: relPath,
+    type: "dir",
+    modifiedMs,
+    children,
+  };
+}
+
 // Async workspace tree walker — recurses through the workspace with
 // the same security filters as the original sync implementation
 // (hidden dirs, sensitive files, symlinks all rejected) and the same
@@ -489,55 +536,23 @@ export async function buildTreeAsync(absPath: string, relPath: string, gitFilter
   // root .gitignore (it's for git, not the UI). Pass a fresh empty
   // filter so children pick up THEIR .gitignore files.
   const localFilter = gitFilter ? gitFilter.childForDir(absPath) : new GitignoreFilter();
-  // Build every surviving child concurrently. Filter:
-  // skip hidden dirs, sensitive files, symlinks, .gitignore matches,
-  // and entries that fail to stat.
+  // Build every surviving child concurrently, recursing into the ones
+  // that pass the visibility filter.
   const childPromises: Promise<TreeNode | null>[] = entries.map(async (entry): Promise<TreeNode | null> => {
-    if (HIDDEN_DIRS.has(entry.name)) return null;
-    if (!entry.isDirectory() && isSensitivePath(entry.name)) return null;
-    if (entry.isSymbolicLink()) return null;
-    const childRel = relPath ? path.join(relPath, entry.name) : entry.name;
-    // .gitignore check: for directories, append trailing / so
-    // directory-only patterns (e.g. "node_modules/") match.
-    if (localFilter) {
-      const testPath = entry.isDirectory() ? `${childRel}/` : childRel;
-      if (localFilter.ignores(testPath)) return null;
-    }
-    const childAbs = path.join(absPath, entry.name);
-    const childStat = await statSafeAsync(childAbs);
-    if (!childStat) return null;
-    return buildTreeAsync(childAbs, childRel, localFilter);
-  });
-  const resolved = await Promise.all(childPromises);
-  const children = resolved.filter((childNode): childNode is TreeNode => childNode !== null);
-  children.sort((leftChild, rightChild) => {
-    if (leftChild.type !== rightChild.type) return leftChild.type === "dir" ? -1 : 1;
-    return leftChild.name.localeCompare(rightChild.name);
+    const child = await resolveVisibleChild(entry, absPath, relPath, localFilter);
+    if (!child) return null;
+    return buildTreeAsync(child.childAbs, child.childRel, localFilter);
   });
-  return {
-    name: relPath ? path.basename(relPath) : "",
-    path: relPath,
-    type: "dir",
-    modifiedMs: stat.mtimeMs,
-    children,
-  };
+  return assembleDirNode(childPromises, relPath, stat.mtimeMs);
 }
 
 // Map a single directory entry to a shallow TreeNode, applying the
 // same hidden/sensitive/symlink/gitignore filters as the recursive
 // walk. Returns null for entries that should not surface in the UI.
 async function dirEntryToNode(entry: Dirent, absPath: string, relPath: string, localFilter: GitignoreFilter | undefined): Promise<TreeNode | null> {
-  if (HIDDEN_DIRS.has(entry.name)) return null;
-  if (!entry.isDirectory() && isSensitivePath(entry.name)) return null;
-  if (entry.isSymbolicLink()) return null;
-  const childRel = relPath ? path.join(relPath, entry.name) : entry.name;
-  if (localFilter) {
-    const testPath = entry.isDirectory() ? `${childRel}/` : childRel;
-    if (localFilter.ignores(testPath)) return null;
-  }
-  const childAbs = path.join(absPath, entry.name);
-  const childStat = await statSafeAsync(childAbs);
-  if (!childStat) return null;
+  const child = await resolveVisibleChild(entry, absPath, relPath, localFilter);
+  if (!child) return null;
+  const { childRel, childStat } = child;
   if (childStat.isDirectory()) {
     return {
       name: entry.name,
@@ -580,19 +595,7 @@ export async function listDirShallow(absPath: string, relPath: string, gitFilter
   // filter so children pick up THEIR .gitignore files.
   const localFilter = gitFilter ? gitFilter.childForDir(absPath) : new GitignoreFilter();
   const childPromises = entries.map((entry) => dirEntryToNode(entry, absPath, relPath, localFilter));
-  const resolved = await Promise.all(childPromises);
-  const children = resolved.filter((childNode): childNode is TreeNode => childNode !== null);
-  children.sort((leftChild, rightChild) => {
-    if (leftChild.type !== rightChild.type) return leftChild.type === "dir" ? -1 : 1;
-    return leftChild.name.localeCompare(rightChild.name);
-  });
-  return {
-    name: relPath ? path.basename(relPath) : "",
-    path: relPath,
-    type: "dir",
-    modifiedMs: stat.mtimeMs,
-    children,
-  };
+  return assembleDirNode(childPromises, relPath, stat.mtimeMs);
 }
 
 router.get(API_ROUTES.files.tree, async (_req: Request<object, unknown, unknown, object>, res: Response<TreeNode | ErrorResponse>) => {