@karmaniverous/jeeves-server 3.4.2 → 3.5.0

package/src/config/index.ts

@@ -2,15 +2,15 @@
  * @packageDocumentation
  *
  * Config loading and singleton management.
- * Loads config via cosmiconfig, validates with Zod, applies env var substitution,
+ * Loads config from a JSON file, validates with Zod, applies env var substitution,
  * resolves runtime types via resolve.ts, and exposes getConfig()/resetConfig().
  */
 
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { cosmiconfig } from 'cosmiconfig';
-
+import { migrateConfigPath } from './migration.js';
 import { buildRuntimeConfig } from './resolve.js';
 import { jeevesConfigSchema } from './schema.js';
 import { substituteEnvVars } from './substituteEnvVars.js';
@@ -19,59 +19,72 @@ import type { RuntimeConfig } from './types.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, '../../..');
 
-const MODULE_NAME = 'jeeves-server';
-
 /**
- * Load and validate jeeves-server configuration via cosmiconfig.
- *
- * Searches for `jeeves-server.config.{json,yaml,yml,js,ts,cjs,mjs}`
- * or `.jeeves-serverrc` in the package root and parent directories.
+ * Load and validate jeeves-server configuration from a JSON file.
  *
  * @param configPath - Optional explicit path to a config file.
  * @returns Resolved runtime configuration.
  */
-export async function loadConfig(configPath?: string): Promise<RuntimeConfig> {
-  const explorer = cosmiconfig(MODULE_NAME, {
-    searchPlaces: [
-      'package.json',
-      `.${MODULE_NAME}rc`,
-      `.${MODULE_NAME}rc.json`,
-      `.${MODULE_NAME}rc.yaml`,
-      `.${MODULE_NAME}rc.yml`,
-      `${MODULE_NAME}.config.json`,
-      `${MODULE_NAME}.config.yaml`,
-      `${MODULE_NAME}.config.yml`,
-      `${MODULE_NAME}.config.js`,
-      `${MODULE_NAME}.config.ts`,
-      `${MODULE_NAME}.config.mjs`,
-      `${MODULE_NAME}.config.cjs`,
-    ],
-  });
-
-  const result = configPath
-    ? await explorer.load(configPath)
-    : await explorer.search(rootDir);
-
-  if (!result || result.isEmpty) {
+export function loadConfig(configPath?: string): RuntimeConfig {
+  const resolvedPath = configPath
+    ? migrateConfigPath(configPath)
+    : findDefaultConfig();
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(
+      `Configuration file not found: ${resolvedPath}\n` +
+        `Create a jeeves-server config.json file or pass --config <path>.`,
+    );
+  }
+
+  // Reject non-JSON config files
+  const ext = path.extname(resolvedPath).toLowerCase();
+  if (ext && ext !== '.json') {
+    throw new Error(
+      `Unsupported config file format: ${ext}\n` +
+        `Only JSON configuration files are supported. ` +
+        `Please convert your config to JSON format.`,
+    );
+  }
+
+  const rawContent = fs.readFileSync(resolvedPath, 'utf8');
+  let rawConfig: Record<string, unknown>;
+  try {
+    rawConfig = JSON.parse(rawContent) as Record<string, unknown>;
+  } catch (err) {
     throw new Error(
-      `No jeeves-server configuration found. Create a jeeves-server.config.json (or .yaml) file.\n` +
-        `Searched from: ${rootDir}`,
+      `Failed to parse config file ${resolvedPath}: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err },
     );
   }
 
-  const substituted = substituteEnvVars(
-    result.config as Record<string, unknown>,
-  );
+  const substituted = substituteEnvVars(rawConfig);
 
   const parseResult = jeevesConfigSchema.safeParse(substituted);
   if (!parseResult.success) {
     const issues = parseResult.error.issues
       .map((i) => `  - ${i.path.join('.')}: ${i.message}`)
       .join('\n');
-    throw new Error(`Invalid configuration in ${result.filepath}:\n${issues}`);
+    throw new Error(`Invalid configuration in ${resolvedPath}:\n${issues}`);
   }
 
-  return buildRuntimeConfig(parseResult.data, rootDir, result.filepath);
+  return buildRuntimeConfig(parseResult.data, rootDir, resolvedPath);
+}
+
+/**
+ * Find the default config file in the package root directory.
+ */
+function findDefaultConfig(): string {
+  // Try new convention first
+  const newPath = path.join(rootDir, 'jeeves-server', 'config.json');
+  if (fs.existsSync(newPath)) return newPath;
+
+  // Fall back to old convention
+  const oldPath = path.join(rootDir, 'jeeves-server.config.json');
+  if (fs.existsSync(oldPath)) return oldPath;
+
+  // Return new path for error message
+  return newPath;
 }
 
 let configInstance: RuntimeConfig | null = null;
@@ -101,9 +114,9 @@ export function getConfig(): RuntimeConfig {
  * Initialize the config singleton. Must be called once at startup.
  * @param configPath - Optional explicit path to a config file.
  */
-export async function initConfig(configPath?: string): Promise<RuntimeConfig> {
+export function initConfig(configPath?: string): RuntimeConfig {
   lastConfigPath = configPath;
-  configInstance = await loadConfig(configPath);
+  configInstance = loadConfig(configPath);
   return configInstance;
 }
 
@@ -111,8 +124,8 @@ export async function initConfig(configPath?: string): Promise<RuntimeConfig> {
  * Reload the config singleton from the last-used config path.
  * Call after mutating state that affects resolved config (e.g., key rotation).
  */
-export async function resetConfig(): Promise<void> {
-  configInstance = await loadConfig(lastConfigPath);
+export function resetConfig(): void {
+  configInstance = loadConfig(lastConfigPath);
 }
 
 /**

package/src/config/loadConfig.test.ts

@@ -36,28 +36,26 @@ describe('loadConfig', () => {
     clearConfig();
   });
 
-  it('loads a valid JSON config file', async () => {
+  it('loads a valid JSON config file', () => {
     const configPath = writeConfig(tmpDir, VALID_CONFIG);
-    const config = await loadConfig(configPath);
+    const config = loadConfig(configPath);
     expect(config.port).toBe(9999);
     expect(config.chromePath).toBe('/usr/bin/chromium');
-    expect(config.configPath).toBe(configPath);
+    // Migration moves jeeves-server.config.json → jeeves-server/config.json
+    const expectedPath = path.join(tmpDir, 'jeeves-server', 'config.json');
+    expect(config.configPath).toBe(expectedPath);
   });
 
-  it('throws on missing config', async () => {
-    await expect(
-      loadConfig(path.join(tmpDir, 'nonexistent.json')),
-    ).rejects.toThrow();
+  it('throws on missing config', () => {
+    expect(() => loadConfig(path.join(tmpDir, 'nonexistent.json'))).toThrow();
   });
 
-  it('throws on invalid config (missing auth)', async () => {
+  it('throws on invalid config (missing auth)', () => {
     const configPath = writeConfig(tmpDir, { port: 1234 });
-    await expect(loadConfig(configPath)).rejects.toThrow(
-      'Invalid configuration',
-    );
+    expect(() => loadConfig(configPath)).toThrow('Invalid configuration');
   });
 
-  it('applies env var substitution', async () => {
+  it('applies env var substitution', () => {
     const original = process.env['TEST_CHROME_PATH'];
     process.env['TEST_CHROME_PATH'] = '/custom/chrome';
     try {
@@ -65,7 +63,7 @@ describe('loadConfig', () => {
         ...VALID_CONFIG,
         chromePath: '${TEST_CHROME_PATH}',
       });
-      const config = await loadConfig(configPath);
+      const config = loadConfig(configPath);
       expect(config.chromePath).toBe('/custom/chrome');
     } finally {
       if (original === undefined) delete process.env['TEST_CHROME_PATH'];
@@ -73,15 +71,15 @@ describe('loadConfig', () => {
     }
   });
 
-  it('applies default port when omitted', async () => {
+  it('applies default port when omitted', () => {
     const noPort = { ...VALID_CONFIG };
     delete (noPort as Record<string, unknown>).port;
     const configPath = writeConfig(tmpDir, noPort);
-    const config = await loadConfig(configPath);
+    const config = loadConfig(configPath);
     expect(config.port).toBe(1934);
   });
 
-  it('rejects _plugin key with scopes', async () => {
+  it('rejects _plugin key with scopes', () => {
     const configPath = writeConfig(tmpDir, {
       ...VALID_CONFIG,
       keys: {
@@ -89,12 +87,12 @@ describe('loadConfig', () => {
         _plugin: { key: 'c'.repeat(64), scopes: ['/restricted'] },
       },
     });
-    await expect(loadConfig(configPath)).rejects.toThrow(
+    expect(() => loadConfig(configPath)).toThrow(
       '_plugin key must not have scopes',
     );
   });
 
-  it('rejects _internal key with scopes', async () => {
+  it('rejects _internal key with scopes', () => {
     const configPath = writeConfig(tmpDir, {
       ...VALID_CONFIG,
       keys: {
@@ -102,12 +100,12 @@ describe('loadConfig', () => {
         _internal: { key: 'b'.repeat(64), scopes: ['/restricted'] },
       },
     });
-    await expect(loadConfig(configPath)).rejects.toThrow(
+    expect(() => loadConfig(configPath)).toThrow(
       '_internal key must not have scopes',
     );
   });
 
-  it('accepts _plugin key without scopes', async () => {
+  it('accepts _plugin key without scopes', () => {
     const configPath = writeConfig(tmpDir, {
       ...VALID_CONFIG,
       keys: {
@@ -115,13 +113,13 @@ describe('loadConfig', () => {
         _plugin: 'c'.repeat(64),
       },
     });
-    const config = await loadConfig(configPath);
+    const config = loadConfig(configPath);
     expect(config.resolvedKeys.find((k) => k.name === '_plugin')?.seed).toBe(
       'c'.repeat(64),
     );
   });
 
-  it('rejects undefined named scope references', async () => {
+  it('rejects undefined named scope references', () => {
     const configPath = writeConfig(tmpDir, {
       ...VALID_CONFIG,
       scopes: { restricted: { allow: ['/**'], deny: ['/secret'] } },
@@ -131,12 +129,12 @@ describe('loadConfig', () => {
       },
     });
 
-    await expect(loadConfig(configPath)).rejects.toThrow(
+    expect(() => loadConfig(configPath)).toThrow(
       'Scope "missing" is not defined',
     );
   });
 
-  it('does not treat path globs as named scope references', async () => {
+  it('does not treat path globs as named scope references', () => {
     const configPath = writeConfig(tmpDir, {
       ...VALID_CONFIG,
       insiders: {
@@ -144,7 +142,7 @@ describe('loadConfig', () => {
       },
     });
 
-    const config = await loadConfig(configPath);
+    const config = loadConfig(configPath);
     expect(
       config.resolvedInsiders.find((i) => i.email === 'a@example.com')?.scopes,
     ).toEqual({
@@ -173,16 +171,16 @@ describe('config singleton', () => {
     expect(() => getConfig()).toThrow('Config not initialized');
   });
 
-  it('initConfig populates getConfig', async () => {
+  it('initConfig populates getConfig', () => {
     const configPath = writeConfig(tmpDir, VALID_CONFIG);
-    await initConfig(configPath);
+    initConfig(configPath);
     const config = getConfig();
     expect(config.port).toBe(9999);
   });
 
-  it('clearConfig clears the singleton', async () => {
+  it('clearConfig clears the singleton', () => {
     const configPath = writeConfig(tmpDir, VALID_CONFIG);
-    await initConfig(configPath);
+    initConfig(configPath);
     clearConfig();
     expect(() => getConfig()).toThrow('Config not initialized');
   });

package/src/config/migration.ts

@@ -0,0 +1,76 @@
+/**
+ * Config path migration — handles old → new config path convention.
+ *
+ * Old convention: `<configDir>/jeeves-server.config.json`
+ * New convention: `<configDir>/jeeves-server/config.json`
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const NON_JSON_EXTENSIONS = new Set([
+  '.ts',
+  '.yaml',
+  '.yml',
+  '.toml',
+  '.mjs',
+  '.cjs',
+  '.js',
+]);
+
+/**
+ * Migrate config path from old convention to new convention if needed.
+ *
+ * If the passed path matches the old convention (jeeves-server.config.json)
+ * and the new path does not exist, migrates the file. If non-JSON config
+ * is found, rejects with a clear error.
+ *
+ * @param configPath - The config path passed via --config CLI flag.
+ * @returns The resolved config path (may be the new path after migration).
+ */
+export function migrateConfigPath(configPath: string): string {
+  const ext = path.extname(configPath).toLowerCase();
+
+  // Reject non-JSON config files
+  if (NON_JSON_EXTENSIONS.has(ext)) {
+    throw new Error(
+      `Unsupported config file format: ${ext}\n` +
+        `Only JSON configuration files are supported. ` +
+        `Please convert your config to JSON format.`,
+    );
+  }
+
+  const basename = path.basename(configPath);
+  const configDir = path.dirname(configPath);
+
+  // Check if this matches the old convention
+  if (basename !== 'jeeves-server.config.json') {
+    return configPath;
+  }
+
+  const newDir = path.join(configDir, 'jeeves-server');
+  const newPath = path.join(newDir, 'config.json');
+
+  // If new path already exists, use it
+  if (fs.existsSync(newPath)) {
+    console.log(
+      `[config-migration] Using new config path: ${newPath} ` +
+        `(old path ${configPath} is superseded)`,
+    );
+    return newPath;
+  }
+
+  // If old path exists, migrate it
+  if (fs.existsSync(configPath)) {
+    console.log(
+      `[config-migration] Migrating config: ${configPath} → ${newPath}`,
+    );
+    fs.mkdirSync(newDir, { recursive: true });
+    fs.renameSync(configPath, newPath);
+    console.log(`[config-migration] Migration complete.`);
+    return newPath;
+  }
+
+  // Neither exists — return the passed path for downstream error handling
+  return configPath;
+}

package/src/config/schema.ts

@@ -1,4 +1,5 @@
-import { z } from 'zod';
+import { SERVER_PORT } from '@karmaniverous/jeeves';
+import { z } from 'zod';
 
 /** Supported authentication methods */
 export const authModeSchema = z.enum(['google', 'keys']);
@@ -99,7 +100,7 @@ function getScopeRefs(scopes: unknown): string[] {
 /** Top-level Jeeves Server configuration */
 export const jeevesConfigSchema = z
   .object({
-    port: z.number().int().positive().default(1934),
+    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.)
@@ -126,7 +127,7 @@ export const jeevesConfigSchema = z
     roots: z.record(z.string(), z.string()).optional(),
     /**
      * URL of the jeeves-runner API for process dashboard proxy.
-     * Default: 'http://127.0.0.1:3100'
+     * 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. */
@@ -153,7 +154,7 @@ export const jeevesConfigSchema = z
     diagramCachePath: z.string().optional(),
     /**
      * URL of the jeeves-watcher API for semantic search.
-     * When set, the search UI appears in the header. Example: 'http://localhost:3458'
+     * When set, the search UI appears in the header. Example: 'http://127.0.0.1:1936'
      */
     watcherUrl: z.url().optional(),
     /**

package/src/descriptor.ts

@@ -0,0 +1,55 @@
+/**
+ * Server-side JeevesComponentDescriptor for the jeeves-server component.
+ *
+ * @packageDocumentation
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  jeevesComponentDescriptorSchema,
+  SERVER_PORT,
+} from '@karmaniverous/jeeves';
+
+import { jeevesConfigSchema } from './config/schema.js';
+import { packageVersion } from './util/packageVersion.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the start-server entry point (resolves correctly from any cwd). */
+const startServerPath = path.resolve(__dirname, 'cli', 'start-server.js');
+
+export const serverDescriptor = jeevesComponentDescriptorSchema.parse({
+  name: 'server',
+  version: packageVersion,
+  servicePackage: '@karmaniverous/jeeves-server',
+  pluginPackage: '@karmaniverous/jeeves-server-openclaw',
+  defaultPort: SERVER_PORT,
+  configSchema: jeevesConfigSchema,
+  configFileName: 'config.json',
+  initTemplate: () => ({
+    chromePath: 'CHANGE_ME_chromePath',
+    auth: {
+      modes: ['keys'],
+      sessionSecret: 'CHANGE_ME_sessionSecret',
+    },
+    keys: {
+      default: 'CHANGE_ME_defaultKey',
+    },
+  }),
+  onConfigApply: async () => {
+    const { resetConfig } = await import('./config/index.js');
+    resetConfig();
+  },
+  startCommand: (configPath: string) => [
+    'node',
+    startServerPath,
+    '--config',
+    configPath,
+  ],
+  sectionId: 'Server',
+  refreshIntervalSeconds: 61,
+  generateToolsContent: () => '',
+  dependencies: { hard: [], soft: ['watcher', 'runner', 'meta'] },
+});

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

@@ -0,0 +1,200 @@
+/**
+ * Tests for diagram export route handlers.
+ *
+ * Validates the cache-first rendering pipeline shared by Mermaid and PlantUML
+ * handlers, and the path resolution + error handling for both routes.
+ *
+ * @packageDocumentation
+ */
+
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mock config before importing the module under test
+const tmpDir = path.join(tmpdir(), `diagramExport-test-${String(Date.now())}`);
+
+vi.mock('../../config/index.js', () => ({
+  getConfig: () => ({
+    roots: {},
+  }),
+}));
+
+vi.mock('../../services/diagramCache.js', () => {
+  let cache: Record<string, Buffer> = {};
+  return {
+    getCachedDiagramBuffer: (
+      engine: string,
+      source: string,
+      format: string,
+    ) => {
+      const key = `${engine}:${source}:${format}`;
+      return cache[key] ?? null;
+    },
+    cacheDiagramBuffer: (
+      engine: string,
+      source: string,
+      buffer: Buffer,
+      format: string,
+    ) => {
+      cache[`${engine}:${source}:${format}`] = buffer;
+    },
+    _reset: () => {
+      cache = {};
+    },
+  };
+});
+
+vi.mock('../../services/mermaid.js', () => ({
+  renderMermaidToFile: vi.fn(),
+}));
+
+vi.mock('../../services/plantuml.js', () => ({
+  getPlantUmlFormats: () => ['svg', 'png'],
+  renderPlantUmlToBuffer: vi.fn(),
+}));
+
+const { diagramExportRoutes } = await import('./diagramExport.js');
+const { renderMermaidToFile } = await import('../../services/mermaid.js');
+const { renderPlantUmlToBuffer } = await import('../../services/plantuml.js');
+
+/** Minimal Fastify reply mock that captures sent data. */
+function createReplyMock() {
+  const headers: Record<string, string> = {};
+  let sentData: unknown = null;
+  let statusCode = 200;
+  const reply = {
+    code: (c: number) => {
+      statusCode = c;
+      return reply;
+    },
+    header: (key: string, value: string) => {
+      headers[key.toLowerCase()] = value;
+      return reply;
+    },
+    send: (data: unknown) => {
+      sentData = data;
+      return reply;
+    },
+    get statusCode() {
+      return statusCode;
+    },
+    get headers() {
+      return headers;
+    },
+    get sentData() {
+      return sentData;
+    },
+  };
+  return reply;
+}
+
+describe('diagramExportRoutes', () => {
+  const routes: Record<
+    string,
+    (
+      req: { params: Record<string, string>; query: Record<string, string> },
+      reply: ReturnType<typeof createReplyMock>,
+    ) => Promise<void>
+  > = {};
+
+  beforeEach(async () => {
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    const fakeFastify = {
+      get: (
+        routePath: string,
+        handler: (req: unknown, reply: unknown) => Promise<void>,
+      ) => {
+        routes[routePath] = handler as (typeof routes)[string];
+      },
+    };
+
+    await diagramExportRoutes(fakeFastify as never, {});
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it('returns 400 when no path is provided for mermaid export', async () => {
+    const reply = createReplyMock();
+    await routes['/api/mermaid-export/*'](
+      { params: { '*': '' }, query: {} },
+      reply,
+    );
+    expect(reply.statusCode).toBe(400);
+  });
+
+  it('returns 404 for non-existent mermaid file', async () => {
+    const reply = createReplyMock();
+    await routes['/api/mermaid-export/*'](
+      { params: { '*': 'nonexistent.mmd' }, query: {} },
+      reply,
+    );
+    expect(reply.statusCode).toBe(404);
+  });
+
+  it('returns 400 when no path is provided for plantuml export', async () => {
+    const reply = createReplyMock();
+    await routes['/api/plantuml-export/*'](
+      { params: { '*': '' }, query: {} },
+      reply,
+    );
+    expect(reply.statusCode).toBe(400);
+  });
+
+  it('returns 404 for non-existent plantuml file', async () => {
+    const reply = createReplyMock();
+    await routes['/api/plantuml-export/*'](
+      { params: { '*': 'nonexistent.puml' }, query: {} },
+      reply,
+    );
+    expect(reply.statusCode).toBe(404);
+  });
+
+  it('sends 500 when mermaid render returns null', async () => {
+    // Create a real .mmd file
+    const mmdPath = path.join(tmpDir, 'test.mmd');
+    fs.writeFileSync(mmdPath, 'graph TD; A-->B');
+
+    // Mock urlPathToFs to resolve our temp path
+    const platformMod = await import('../../util/platform.js');
+    vi.spyOn(platformMod, 'urlPathToFs').mockReturnValue(mmdPath);
+
+    vi.mocked(renderMermaidToFile).mockResolvedValue(null);
+
+    const reply = createReplyMock();
+    await routes['/api/mermaid-export/*'](
+      { params: { '*': 'test.mmd' }, query: { format: 'svg' } },
+      reply,
+    );
+    expect(reply.statusCode).toBe(500);
+    expect((reply.sentData as Record<string, string>).error).toContain(
+      'render failed',
+    );
+  });
+
+  it('sends 500 when plantuml render returns null', async () => {
+    const pumlPath = path.join(tmpDir, 'test.puml');
+    fs.writeFileSync(pumlPath, '@startuml\nA -> B\n@enduml');
+
+    const platformMod = await import('../../util/platform.js');
+    vi.spyOn(platformMod, 'urlPathToFs').mockReturnValue(pumlPath);
+
+    vi.mocked(renderPlantUmlToBuffer).mockResolvedValue(null);
+
+    const reply = createReplyMock();
+    await routes['/api/plantuml-export/*'](
+      { params: { '*': 'test.puml' }, query: { format: 'svg' } },
+      reply,
+    );
+    expect(reply.statusCode).toBe(500);
+    expect((reply.sentData as Record<string, string>).error).toContain(
+      'render failed',
+    );
+  });
+});