@karmaniverous/jeeves-server 3.5.2 → 3.6.1

package/guides/setup.md

@@ -6,7 +6,7 @@ title: "Setup & Configuration"
 
 ## Prerequisites
 
-- **Node.js** ≥ 20
+- **Node.js** ≥ 22
 - **Chrome or Chromium** — required for PDF export (Puppeteer uses it headlessly)
 
 ## Installation
@@ -64,9 +64,7 @@ Legacy paths (`jeeves-server.config.json`) are auto-migrated to the new conventi
       "scopes": ["/event"]
     }
   },
-  "events": {},
-  "watcherUrl": "http://localhost:1936",
-  "runnerUrl": "http://127.0.0.1:1937"
+  "events": {}
 }
 ```
 
@@ -285,18 +283,22 @@ See the [Event Gateway](event-gateway.md) guide for full configuration and usage
 
 ### jeeves-watcher (Semantic Search)
 
-When `watcherUrl` is configured, the server proxies semantic search queries to [jeeves-watcher](https://github.com/karmaniverous/jeeves-watcher) and provides a search UI in the header, with filter facets and scope-aware result filtering.
+The server proxies semantic search queries to [jeeves-watcher](https://github.com/karmaniverous/jeeves-watcher) and provides a search UI in the header, with filter facets and scope-aware result filtering. The watcher URL is resolved automatically via core service discovery (default port 1936).
+
+To override the default URL, configure it in `{configRoot}/jeeves-core/config.json`:
 
 ```json
-{ "watcherUrl": "http://localhost:1936" }
+{ "services": { "watcher": { "url": "http://custom-host:1936" } } }
 ```
 
 ### jeeves-runner (Process Dashboard)
 
-When `runnerUrl` is configured, the server proxies runner API calls for the process dashboard UI.
+The server proxies runner API calls for the process dashboard UI. The runner URL is resolved automatically via core service discovery (default port 1937).
+
+To override the default URL, configure it in `{configRoot}/jeeves-core/config.json`:
 
 ```json
-{ "runnerUrl": "http://127.0.0.1:1937" }
+{ "services": { "runner": { "url": "http://custom-host:1937" } } }
 ```
 
 ### PlantUML
@@ -336,8 +338,10 @@ If `plantuml` is omitted entirely, only the community server is used.
 | `eventLogPurgeMs` | number | `2592000000` | Event log retention (default: 30 days) |
 | `maxZipSizeMb` | number | `100` | Max directory size for ZIP export |
 | `roots` | object | — | Linux filesystem roots (ignored on Windows) |
-| `watcherUrl` | string | — | jeeves-watcher API URL for semantic search |
-| `runnerUrl` | string | — | jeeves-runner API URL for process dashboard |
+| ~~`watcherUrl`~~ | — | — | **Deprecated in v3.6.0.** Use core service discovery. |
+| ~~`runnerUrl`~~ | — | — | **Deprecated in v3.6.0.** Use core service discovery. |
+| ~~`host`~~ | — | — | **Deprecated in v3.6.0.** Use `getBindAddress()` via core. |
+| ~~`metaUrl`~~ | — | — | **Deprecated in v3.6.0.** Use core service discovery. |
 | `plantuml` | object | — | PlantUML rendering config |
 | `diagramCachePath` | string | `.diagram-cache` | Cached rendered diagram directory |
 | `outsiderPolicy` | scopes | — | Global outsider sharing constraints |

package/knip.json

@@ -1,7 +1,8 @@
 {
   "$schema": "https://unpkg.com/knip@latest/schema.json",
   "entry": [
-    "src/cli/index.ts"
+    "src/cli/index.ts",
+    "src/cli/start-server.ts"
   ],
   "project": [
     "src/**/*.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-server",
-  "version": "3.5.2",
+  "version": "3.6.1",
   "description": "Secure file browser, markdown viewer, and webhook gateway with PDF/DOCX export and expiring share links",
   "keywords": [
     "fastify",
@@ -48,19 +48,18 @@
   "dependencies": {
     "@fastify/cookie": "^11.0.2",
     "@fastify/static": "^8.3.0",
-    "@karmaniverous/jeeves": "^0.4.6",
-    "@karmaniverous/jsonmap": "^0.3.1",
+    "@karmaniverous/jeeves": "^0.5.3",
+    "@karmaniverous/jsonmap": "^2.1.1",
     "@mermaid-js/mermaid-cli": "^11.12.0",
-    "@turbodocx/html-to-docx": "^1.1.0",
-    "ajv": "^8.17.1",
+    "@turbodocx/html-to-docx": "^1.20.1",
+    "ajv": "^8.18.0",
     "archiver": "^7.0.1",
     "cheerio": "^1.2.0",
-    "fastify": "^5.2.3",
+    "fastify": "^5.8.4",
     "lz-string": "^1.5.0",
-    "marked": "^17.0.1",
+    "marked": "^17.0.5",
     "mime-types": "^3.0.2",
-    "package-directory": "^8.2.0",
-    "picomatch": "^4.0.3",
+    "picomatch": "^4.0.4",
     "plantuml-encoder": "^1.4.0",
     "puppeteer": "^23.11.1",
     "puppeteer-core": "^23.11.1",
@@ -68,18 +67,18 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.54.1",
+    "@dotenvx/dotenvx": "^1.59.1",
     "@types/archiver": "^7.0.0",
     "@types/mime-types": "^3.0.1",
-    "@types/node": "^22.0.0",
-    "@types/picomatch": "^4.0.2",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@types/node": "^25.5.2",
+    "@types/picomatch": "^4.0.3",
+    "@vitest/coverage-v8": "^4.1.2",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
-    "happy-dom": "^20.0.11",
+    "happy-dom": "^20.8.9",
     "release-it": "^19.2.4",
-    "rimraf": "^6.0.1",
-    "vitest": "^4.0.16"
+    "rimraf": "^6.1.3",
+    "vitest": "^4.1.2"
   },
   "auto-changelog": {
     "output": "CHANGELOG.md",
@@ -119,6 +118,9 @@
       "publish": true
     }
   },
+  "engines": {
+    "node": ">=22"
+  },
   "bin": {
     "jeeves-server": "./dist/src/cli/index.js"
   }

package/src/cli/index.ts

@@ -9,7 +9,9 @@
  * @packageDocumentation
  */
 
-import { createServiceCli } from '@karmaniverous/jeeves';
+import { checkNodeVersion, createServiceCli } from '@karmaniverous/jeeves';
+
+checkNodeVersion();
 
 import { serverDescriptor } from '../descriptor.js';
 

package/src/cli/start-server.ts

@@ -9,12 +9,26 @@
  * The CLI's `start` command uses this same logic in-process.
  */
 
+import { checkNodeVersion, init } from '@karmaniverous/jeeves';
+
+checkNodeVersion();
+
 import { initConfig } from '../config/index.js';
 
-const configIndex = process.argv.indexOf('--config');
-const configPath =
-  configIndex !== -1 ? process.argv[configIndex + 1] : undefined;
+function parseArg(name: string): string | undefined {
+  const idx = process.argv.indexOf(name);
+  return idx !== -1 && process.argv[idx + 1]
+    ? process.argv[idx + 1]
+    : undefined;
+}
+
+const configPath = parseArg('--config');
+const workspace =
+  parseArg('--workspace') ?? process.env['JEEVES_WORKSPACE'] ?? '.';
+const configRoot =
+  parseArg('--config-root') ?? process.env['JEEVES_CONFIG_ROOT'] ?? './config';
 
+init({ workspacePath: workspace, configRoot });
 initConfig(configPath);
 
 // Dynamic import to ensure config is initialized before server modules load

package/src/config/index.ts

@@ -12,7 +12,7 @@ import { fileURLToPath } from 'node:url';
 
 import { migrateConfigPath } from './migration.js';
 import { buildRuntimeConfig } from './resolve.js';
-import { jeevesConfigSchema } from './schema.js';
+import { DEPRECATED_CONFIG_PROPS, jeevesConfigSchema } from './schema.js';
 import { substituteEnvVars } from './substituteEnvVars.js';
 import type { RuntimeConfig } from './types.js';
 
@@ -58,7 +58,27 @@ export function loadConfig(configPath?: string): RuntimeConfig {
     );
   }
 
-  const substituted = substituteEnvVars(rawConfig);
+  // Strip deprecated v3.6.0 properties before validation
+  const cleanedConfig: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(rawConfig)) {
+    if (
+      DEPRECATED_CONFIG_PROPS.includes(
+        key as (typeof DEPRECATED_CONFIG_PROPS)[number],
+      )
+    ) {
+      console.warn(
+        `[jeeves-server] Deprecated config property "${key}" ignored. ` +
+          `Companion service URLs are now resolved via core config ` +
+          `({configRoot}/jeeves-core/config.json services.{name}.url). ` +
+          `Bind address is resolved via getBindAddress(). ` +
+          `Remove "${key}" from ${resolvedPath} to silence this warning.`,
+      );
+    } else {
+      cleanedConfig[key] = value;
+    }
+  }
+
+  const substituted = substituteEnvVars(cleanedConfig);
 
   const parseResult = jeevesConfigSchema.safeParse(substituted);
   if (!parseResult.success) {

package/src/config/loadConfig.test.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { clearConfig, getConfig, initConfig, loadConfig } from './index.js';
 
@@ -154,6 +154,82 @@ describe('loadConfig', () => {
   });
 });
 
+describe('deprecated config property migration', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-config-'));
+    clearConfig();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    clearConfig();
+  });
+
+  it('loads config with deprecated host, watcherUrl, runnerUrl, metaUrl', () => {
+    const configWithDeprecated = {
+      ...VALID_CONFIG,
+      host: '0.0.0.0',
+      watcherUrl: 'http://localhost:1936',
+      runnerUrl: 'http://localhost:1937',
+      metaUrl: 'http://localhost:1938',
+    };
+    const configPath = writeConfig(tmpDir, configWithDeprecated);
+    const config = loadConfig(configPath);
+    expect(config.port).toBe(9999);
+  });
+
+  it('logs deprecation warnings for each deprecated property', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const configWithDeprecated = {
+        ...VALID_CONFIG,
+        host: '0.0.0.0',
+        watcherUrl: 'http://localhost:1936',
+        runnerUrl: 'http://localhost:1937',
+        metaUrl: 'http://localhost:1938',
+      };
+      const configPath = writeConfig(tmpDir, configWithDeprecated);
+      loadConfig(configPath);
+
+      const deprecatedKeys = ['host', 'watcherUrl', 'runnerUrl', 'metaUrl'];
+      for (const key of deprecatedKeys) {
+        expect(
+          warnSpy.mock.calls.some(
+            (call) =>
+              typeof call[0] === 'string' && call[0].includes(`"${key}"`),
+          ),
+        ).toBe(true);
+      }
+      expect(warnSpy).toHaveBeenCalledTimes(4);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('strips deprecated properties from the resulting RuntimeConfig', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const configWithDeprecated = {
+        ...VALID_CONFIG,
+        host: '0.0.0.0',
+        watcherUrl: 'http://localhost:1936',
+      };
+      const configPath = writeConfig(tmpDir, configWithDeprecated);
+      const config = loadConfig(configPath);
+
+      const configAsRecord = config as unknown as Record<string, unknown>;
+      expect(configAsRecord['host']).toBeUndefined();
+      expect(configAsRecord['watcherUrl']).toBeUndefined();
+      expect(configAsRecord['runnerUrl']).toBeUndefined();
+      expect(configAsRecord['metaUrl']).toBeUndefined();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
+
 describe('config singleton', () => {
   let tmpDir: string;
 

package/src/config/resolve.test.ts

@@ -236,8 +236,6 @@ describe('buildRuntimeConfig', () => {
   it('constructs correct path fields', () => {
     const config = {
       port: 1934,
-      host: '0.0.0.0',
-      metaUrl: 'http://127.0.0.1:1938',
       eventTimeoutMs: 30000,
       eventLogPurgeMs: 2592000000,
       maxZipSizeMb: 100,

package/src/config/resolve.ts

@@ -250,7 +250,6 @@ export function buildRuntimeConfig(
 
   return {
     port: config.port,
-    host: config.host,
     eventTimeoutMs: config.eventTimeoutMs,
     eventLogPurgeMs: config.eventLogPurgeMs,
     maxZipSizeMb: config.maxZipSizeMb,
@@ -284,9 +283,6 @@ export function buildRuntimeConfig(
     googleAuth: config.auth.google ?? null,
     sessionSecret: config.auth.sessionSecret ?? null,
     internalInsiderKey: deriveInternalKey(resolvedKeys),
-    runnerUrl: config.runnerUrl,
-    watcherUrl: config.watcherUrl,
-    metaUrl: config.metaUrl,
     diagramCachePath: config.diagramCachePath,
     configPath,
     eventsLog: path.join(rootDir, 'logs', 'webhook-events.jsonl'),

package/src/config/schema.ts

@@ -1,6 +1,14 @@
 import { SERVER_PORT } from '@karmaniverous/jeeves';
 import { z } from 'zod';
 
+/** Config properties deprecated in v3.6.0 (now resolved via core services). */
+export const DEPRECATED_CONFIG_PROPS = [
+  'host',
+  'runnerUrl',
+  'watcherUrl',
+  'metaUrl',
+] as const;
+
 /** Supported authentication methods */
 export const authModeSchema = z.enum(['google', 'keys']);
 
@@ -101,12 +109,6 @@ function getScopeRefs(scopes: unknown): string[] {
 export const jeevesConfigSchema = z
   .object({
     port: z.number().int().positive().default(SERVER_PORT),
-    /**
-     * Network interface to bind the server to.
-     * Default: '0.0.0.0' (all interfaces — required for external access by insiders, share links, etc.)
-     * Set to '127.0.0.1' to restrict to loopback only.
-     */
-    host: z.string().min(1).default('0.0.0.0'),
     chromePath: z.string().min(1),
     auth: authSchema,
     /** Named scope definitions, referenced by insiders/keys/outsiderPolicy */
@@ -125,11 +127,6 @@ export const jeevesConfigSchema = z
      * Default: \{ root: '/' \}
      */
     roots: z.record(z.string(), z.string()).optional(),
-    /**
-     * URL of the jeeves-runner API for process dashboard proxy.
-     * Default: 'http://127.0.0.1:1937'
-     */
-    runnerUrl: z.url().optional(),
     /** @deprecated Mermaid is now bundled. This field is ignored but kept for backward compatibility. */
     mermaidCliPath: z.string().optional(),
     /**
@@ -152,16 +149,6 @@ export const jeevesConfigSchema = z
      * Defaults to `.diagram-cache` in the server working directory.
      */
     diagramCachePath: z.string().optional(),
-    /**
-     * URL of the jeeves-watcher API for semantic search.
-     * When set, the search UI appears in the header. Example: 'http://127.0.0.1:1936'
-     */
-    watcherUrl: z.url().optional(),
-    /**
-     * URL of the jeeves-meta API for synthesis engine health checks.
-     * Default: 'http://127.0.0.1:1938'
-     */
-    metaUrl: z.url().default('http://127.0.0.1:1938'),
     /**
      * Global outsider policy â€" constrains which paths are eligible for outsider sharing.
      * Uses the same allow/deny model as insider scopes.

package/src/config/substituteEnvVars.ts

@@ -3,6 +3,8 @@
  *
  * Deep-walks config objects and replaces `${VAR_NAME}` patterns with environment variable values.
  * Ported from jeeves-watcher — candidate for hoisting to shared `@karmaniverous/jeeves-config`.
+ *
+ * // TODO: replace with core utility when hoisted (see jeeves-core issue for substituteEnvVars hoist)
  */
 
 const ENV_PATTERN = /\$\{([^}]+)\}/g;

package/src/config/types.ts

@@ -50,7 +50,6 @@ export interface ResolvedInsider {
  */
 export interface RuntimeConfig {
   port: number;
-  host: string;
   eventTimeoutMs: number;
   eventLogPurgeMs: number;
   maxZipSizeMb: number;
@@ -63,9 +62,6 @@ export interface RuntimeConfig {
     servers: string[];
   };
   diagramCachePath?: string;
-  runnerUrl?: string;
-  watcherUrl?: string;
-  metaUrl?: string;
   outsiderPolicy: NormalizedScopes | null;
   events: JeevesConfig['events'];
   authModes: AuthMode[];

package/src/descriptor.ts

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import {
+  init,
   jeevesComponentDescriptorSchema,
   SERVER_PORT,
 } from '@karmaniverous/jeeves';
@@ -38,11 +39,18 @@ export const serverDescriptor = jeevesComponentDescriptorSchema.parse({
       default: 'CHANGE_ME_defaultKey',
     },
   }),
-  onConfigApply: async () => {
+  onConfigApply: async (config: Record<string, unknown> | undefined) => {
+    void config; // config argument reserved for future use
     const { resetConfig } = await import('./config/index.js');
     resetConfig();
   },
   run: async (configPath: string) => {
+    // Ensure core init() runs before server modules that depend on
+    // getServiceUrl() / getBindAddress()
+    init({
+      workspacePath: process.env['JEEVES_WORKSPACE'] ?? '.',
+      configRoot: process.env['JEEVES_CONFIG_ROOT'] ?? './config',
+    });
     const { initConfig } = await import('./config/index.js');
     initConfig(configPath);
     await import('./server.js');

package/src/routes/api/auth-status.ts

@@ -50,7 +50,7 @@ export const authStatusRoutes: FastifyPluginAsync = async (fastify) => {
           picture,
           isInsider: !!insider?.seed,
           keyCreatedAt: insider?.keyCreatedAt ?? null,
-          searchEnabled: !!config.watcherUrl,
+          searchEnabled: true,
         });
       }
 

package/src/routes/api/directory.test.ts

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { mapDirectoryEntry } from './directory.js';
+
+describe('directory entry mapping', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-dir-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns itemCount for directory entries', async () => {
+    const subDir = path.join(tmpDir, 'sub');
+    fs.mkdirSync(subDir);
+    fs.writeFileSync(path.join(subDir, 'a.txt'), 'a');
+    fs.writeFileSync(path.join(subDir, 'b.txt'), 'b');
+
+    const entries = fs.readdirSync(tmpDir, { withFileTypes: true });
+    const dirEntry = entries.find((e) => e.name === 'sub');
+    expect(dirEntry).toBeDefined();
+    const mapped = await mapDirectoryEntry(dirEntry!, tmpDir);
+    expect(mapped.type).toBe('directory');
+    expect(mapped.itemCount).toBe(2);
+  });
+
+  it('returns null itemCount for file entries', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'file.txt'), 'content');
+    const entries = fs.readdirSync(tmpDir, { withFileTypes: true });
+    const fileEntry = entries.find((e) => e.name === 'file.txt');
+    expect(fileEntry).toBeDefined();
+    const mapped = await mapDirectoryEntry(fileEntry!, tmpDir);
+    expect(mapped.type).toBe('file');
+    expect(mapped.itemCount).toBeNull();
+    expect(mapped.size).toBeGreaterThan(0);
+  });
+
+  it('counts mixed contents (files + subdirectories)', async () => {
+    const subDir = path.join(tmpDir, 'mixed');
+    fs.mkdirSync(subDir);
+    fs.writeFileSync(path.join(subDir, 'file1.txt'), 'a');
+    fs.writeFileSync(path.join(subDir, 'file2.txt'), 'b');
+    fs.mkdirSync(path.join(subDir, 'nested'));
+
+    const entries = fs.readdirSync(tmpDir, { withFileTypes: true });
+    const dirEntry = entries.find((e) => e.name === 'mixed');
+    expect(dirEntry).toBeDefined();
+    const mapped = await mapDirectoryEntry(dirEntry!, tmpDir);
+    expect(mapped.itemCount).toBe(3);
+  });
+
+  it('returns null itemCount when directory read fails', async () => {
+    const fakeDirent = {
+      name: 'nonexistent',
+      isDirectory: () => true,
+      isFile: () => false,
+      isBlockDevice: () => false,
+      isCharacterDevice: () => false,
+      isFIFO: () => false,
+      isSocket: () => false,
+      isSymbolicLink: () => false,
+      parentPath: tmpDir,
+      path: tmpDir,
+    } as fs.Dirent;
+
+    const mapped = await mapDirectoryEntry(fakeDirent, tmpDir);
+    expect(mapped.itemCount).toBeNull();
+    expect(mapped.mtime).toBeNull();
+  });
+});

package/src/routes/api/directory.ts

@@ -5,6 +5,7 @@
  */
 
 import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import path from 'node:path';
 
 import type { FastifyPluginAsync } from 'fastify';
@@ -23,6 +24,57 @@ import {
   urlPathToFs,
 } from '../../util/platform.js';
 
+/** Result shape returned by {@link mapDirectoryEntry}. */
+export interface DirectoryEntryInfo {
+  name: string;
+  type: string;
+  ext: string;
+  size: number | null;
+  mtime: string | null;
+  itemCount: number | null;
+}
+
+/**
+ * Map a single directory entry to its API representation.
+ *
+ * Uses async fs operations so the event loop is not blocked
+ * when listing large directories.
+ */
+export async function mapDirectoryEntry(
+  entry: fs.Dirent,
+  parentDir: string,
+): Promise<DirectoryEntryInfo> {
+  const entryPath = path.join(parentDir, entry.name);
+  let size: number | null = null;
+  let mtime: string | null = null;
+  let itemCount: number | null = null;
+  const ext = path.extname(entry.name).toLowerCase();
+  try {
+    const entryStats = await fsp.stat(entryPath);
+    mtime = entryStats.mtime.toISOString().split('T')[0];
+    if (entry.isDirectory()) {
+      try {
+        const children = await fsp.readdir(entryPath);
+        itemCount = children.length;
+      } catch {
+        /* permission denied, etc. */
+      }
+    } else {
+      size = entryStats.size;
+    }
+  } catch {
+    /* ignore */
+  }
+  return {
+    name: entry.name,
+    type: entry.isDirectory() ? 'directory' : 'file',
+    ext,
+    size,
+    mtime,
+    itemCount,
+  };
+}
+
 // eslint-disable-next-line @typescript-eslint/require-await
 export const directoryRoutes: FastifyPluginAsync = async (fastify) => {
   const roots = getRoots(getConfig().roots);
@@ -41,7 +93,7 @@ export const directoryRoutes: FastifyPluginAsync = async (fastify) => {
         return reply.code(404).send({ error: 'Not found', path: resolved });
       }
 
-      const stats = fs.statSync(resolved);
+      const stats = await fsp.stat(resolved);
       if (!stats.isDirectory()) {
         const ext = path.extname(resolved).toLowerCase();
         return reply.send({
@@ -56,7 +108,9 @@ export const directoryRoutes: FastifyPluginAsync = async (fastify) => {
       const isInsider = request.accessMode === 'insider';
       const insiderScopes = request.insiderScopes ?? null;
 
-      const allEntries = fs.readdirSync(resolved, { withFileTypes: true });
+      const allEntries = await fsp.readdir(resolved, {
+        withFileTypes: true,
+      });
 
       const entries = insiderScopes
         ? allEntries.filter((entry) => {
@@ -82,26 +136,9 @@ export const directoryRoutes: FastifyPluginAsync = async (fastify) => {
         return a.name.localeCompare(b.name);
       });
 
-      const result = sorted.map((entry) => {
-        const entryPath = path.join(resolved, entry.name);
-        let size: number | null = null;
-        let mtime: string | null = null;
-        const ext = path.extname(entry.name).toLowerCase();
-        try {
-          const entryStats = fs.statSync(entryPath);
-          mtime = entryStats.mtime.toISOString().split('T')[0];
-          if (!entry.isDirectory()) size = entryStats.size;
-        } catch {
-          /* ignore */
-        }
-        return {
-          name: entry.name,
-          type: entry.isDirectory() ? 'directory' : 'file',
-          ext,
-          size,
-          mtime,
-        };
-      });
+      const result = await Promise.all(
+        sorted.map((entry) => mapDirectoryEntry(entry, resolved)),
+      );
 
       const breadcrumbs = breadcrumbParts(resolved, roots);
       const matchedPath = request.authMatchedPath ?? null;