@karmaniverous/jeeves-server 3.0.0-0

package/src/cli/commands/service.ts

@@ -0,0 +1,129 @@
+/**
+ * @packageDocumentation
+ *
+ * CLI commands: service install, service uninstall, service start/stop/restart.
+ */
+
+import { Command } from '@commander-js/extra-typings';
+
+const DEFAULT_SERVICE_NAME = 'JeevesServer';
+const LINUX_SERVICE_NAME = 'jeeves-server';
+
+export function registerServiceCommand(cli: Command): void {
+  const service = cli
+    .command('service')
+    .description('System service management');
+
+  service.addCommand(
+    new Command('install')
+      .description('Print install instructions for a system service')
+      .option('-c, --config <path>', 'Path to configuration file')
+      .option(
+        '-n, --name <name>',
+        'Service name',
+        process.platform === 'win32'
+          ? DEFAULT_SERVICE_NAME
+          : LINUX_SERVICE_NAME,
+      )
+      .action((options) => {
+        const name = options.name;
+        const configArg = options.config ? ` --config "${options.config}"` : '';
+
+        if (process.platform === 'win32') {
+          console.log('# NSSM install commands:');
+          console.log(
+            `nssm install ${name} node "%CD%\\node_modules\\@karmaniverous\\jeeves-server\\dist\\src\\cli\\index.js" start${configArg}`,
+          );
+          console.log(`nssm set ${name} AppDirectory "%CD%"`);
+          console.log(`nssm set ${name} AppStdout "%CD%\\logs\\service.log"`);
+          console.log(
+            `nssm set ${name} AppStderr "%CD%\\logs\\service-error.log"`,
+          );
+          console.log(`nssm set ${name} Start SERVICE_AUTO_START`);
+          console.log(`nssm start ${name}`);
+          return;
+        }
+
+        const unit = [
+          '[Unit]',
+          'Description=Jeeves Server',
+          'After=network.target',
+          '',
+          '[Service]',
+          'Type=simple',
+          'WorkingDirectory=%h',
+          `ExecStart=/usr/bin/env jeeves-server start${configArg}`,
+          'Restart=on-failure',
+          '',
+          '[Install]',
+          'WantedBy=default.target',
+        ].join('\n');
+
+        console.log('# systemd unit file');
+        console.log(`# Save to: ~/.config/systemd/user/${name}.service`);
+        console.log('');
+        console.log(unit);
+        console.log('');
+        console.log('# Then run:');
+        console.log('systemctl --user daemon-reload');
+        console.log(`systemctl --user enable --now ${name}.service`);
+      }),
+  );
+
+  service.addCommand(
+    new Command('uninstall')
+      .description('Print uninstall instructions for a system service')
+      .option(
+        '-n, --name <name>',
+        'Service name',
+        process.platform === 'win32'
+          ? DEFAULT_SERVICE_NAME
+          : LINUX_SERVICE_NAME,
+      )
+      .action((options) => {
+        const name = options.name;
+
+        if (process.platform === 'win32') {
+          console.log('# NSSM uninstall commands:');
+          console.log(`nssm stop ${name}`);
+          console.log(`nssm remove ${name} confirm`);
+          return;
+        }
+
+        console.log('# systemd uninstall:');
+        console.log(`systemctl --user disable --now ${name}.service`);
+        console.log(`rm ~/.config/systemd/user/${name}.service`);
+        console.log('systemctl --user daemon-reload');
+      }),
+  );
+
+  for (const action of ['start', 'stop', 'restart'] as const) {
+    service.addCommand(
+      new Command(action)
+        .description(
+          `${action.charAt(0).toUpperCase() + action.slice(1)} the system service`,
+        )
+        .option(
+          '-n, --name <name>',
+          'Service name',
+          process.platform === 'win32'
+            ? DEFAULT_SERVICE_NAME
+            : LINUX_SERVICE_NAME,
+        )
+        .action((options) => {
+          const name = options.name;
+
+          if (process.platform === 'win32') {
+            if (action === 'restart') {
+              console.log(`nssm restart ${name}`);
+            } else {
+              console.log(`nssm ${action} ${name}`);
+            }
+            return;
+          }
+
+          console.log(`systemctl --user ${action} ${name}.service`);
+        }),
+    );
+  }
+}

package/src/cli/commands/start.ts

@@ -0,0 +1,27 @@
+/**
+ * @packageDocumentation
+ *
+ * CLI command: start — launches the Fastify server.
+ */
+
+import type { Command } from '@commander-js/extra-typings';
+
+export function registerStartCommand(cli: Command): void {
+  cli
+    .command('start')
+    .description('Start the jeeves-server')
+    .option('-c, --config <path>', 'Path to configuration file')
+    .action(async (options) => {
+      try {
+        // Dynamic import to avoid loading server code at CLI parse time
+        const { initConfig } = await import('../../config/index.js');
+        await initConfig(options.config);
+
+        // Import server after config is initialized
+        await import('../../server.js');
+      } catch (error) {
+        console.error('Failed to start:', error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/index.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * @packageDocumentation
+ *
+ * jeeves-server CLI entrypoint.
+ * Commands: start, config validate, config show, service install/uninstall.
+ */
+
+import { Command } from '@commander-js/extra-typings';
+
+import { packageVersion } from '../util/packageVersion.js';
+import { registerConfigCommand } from './commands/config.js';
+import { registerServiceCommand } from './commands/service.js';
+import { registerStartCommand } from './commands/start.js';
+
+const cli = new Command()
+  .name('jeeves-server')
+  .description('Self-hosted file browser, document server, and webhook gateway')
+  .version(packageVersion);
+
+registerStartCommand(cli);
+registerConfigCommand(cli);
+registerServiceCommand(cli);
+
+cli.parse();

package/src/config/index.ts

@@ -0,0 +1,113 @@
+/**
+ * @packageDocumentation
+ *
+ * Config loading and singleton management.
+ * Loads config via cosmiconfig, validates with Zod, applies env var substitution,
+ * resolves runtime types via resolve.ts, and exposes getConfig()/resetConfig().
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { cosmiconfig } from 'cosmiconfig';
+
+import { buildRuntimeConfig } from './resolve.js';
+import { jeevesConfigSchema } from './schema.js';
+import { substituteEnvVars } from './substituteEnvVars.js';
+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.
+ *
+ * @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) {
+    throw new Error(
+      `No jeeves-server configuration found. Create a jeeves-server.config.json (or .yaml) file.\n` +
+        `Searched from: ${rootDir}`,
+    );
+  }
+
+  const substituted = substituteEnvVars(
+    result.config as Record<string, unknown>,
+  );
+
+  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}`);
+  }
+
+  return buildRuntimeConfig(parseResult.data, rootDir, result.filepath);
+}
+
+let configInstance: RuntimeConfig | null = null;
+
+/**
+ * Check if the config singleton has been initialized.
+ */
+export function isConfigInitialized(): boolean {
+  return configInstance !== null;
+}
+
+/**
+ * Get the singleton config instance. Initializes on first call.
+ * @throws If config has not been initialized — call initConfig() first.
+ */
+export function getConfig(): RuntimeConfig {
+  if (!configInstance) {
+    throw new Error(
+      'Config not initialized. Call initConfig() before getConfig().',
+    );
+  }
+  return configInstance;
+}
+
+/**
+ * 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> {
+  configInstance = await loadConfig(configPath);
+  return configInstance;
+}
+
+/**
+ * Reset the config singleton (for testing).
+ */
+export function resetConfig(): void {
+  configInstance = null;
+}

package/src/config/loadConfig.test.ts

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { getConfig, initConfig, loadConfig, resetConfig } from './index.js';
+
+const VALID_CONFIG = {
+  port: 9999,
+  chromePath: '/usr/bin/chromium',
+  auth: { modes: ['keys'] },
+  keys: {
+    primary: 'a'.repeat(64),
+    _internal: 'b'.repeat(64),
+  },
+  events: {},
+};
+
+function writeConfig(dir: string, config: unknown): string {
+  const filePath = path.join(dir, 'jeeves-server.config.json');
+  fs.writeFileSync(filePath, JSON.stringify(config));
+  return filePath;
+}
+
+describe('loadConfig', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-config-'));
+    resetConfig();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    resetConfig();
+  });
+
+  it('loads a valid JSON config file', async () => {
+    const configPath = writeConfig(tmpDir, VALID_CONFIG);
+    const config = await loadConfig(configPath);
+    expect(config.port).toBe(9999);
+    expect(config.chromePath).toBe('/usr/bin/chromium');
+    expect(config.configPath).toBe(configPath);
+  });
+
+  it('throws on missing config', async () => {
+    await expect(
+      loadConfig(path.join(tmpDir, 'nonexistent.json')),
+    ).rejects.toThrow();
+  });
+
+  it('throws on invalid config (missing auth)', async () => {
+    const configPath = writeConfig(tmpDir, { port: 1234 });
+    await expect(loadConfig(configPath)).rejects.toThrow(
+      'Invalid configuration',
+    );
+  });
+
+  it('applies env var substitution', async () => {
+    const original = process.env['TEST_CHROME_PATH'];
+    process.env['TEST_CHROME_PATH'] = '/custom/chrome';
+    try {
+      const configPath = writeConfig(tmpDir, {
+        ...VALID_CONFIG,
+        chromePath: '${TEST_CHROME_PATH}',
+      });
+      const config = await loadConfig(configPath);
+      expect(config.chromePath).toBe('/custom/chrome');
+    } finally {
+      if (original === undefined) delete process.env['TEST_CHROME_PATH'];
+      else process.env['TEST_CHROME_PATH'] = original;
+    }
+  });
+
+  it('applies default port when omitted', async () => {
+    const noPort = { ...VALID_CONFIG };
+    delete (noPort as Record<string, unknown>).port;
+    const configPath = writeConfig(tmpDir, noPort);
+    const config = await loadConfig(configPath);
+    expect(config.port).toBe(1934);
+  });
+
+  it('rejects _plugin key with scopes', async () => {
+    const configPath = writeConfig(tmpDir, {
+      ...VALID_CONFIG,
+      keys: {
+        ...VALID_CONFIG.keys,
+        _plugin: { key: 'c'.repeat(64), scopes: ['/restricted'] },
+      },
+    });
+    await expect(loadConfig(configPath)).rejects.toThrow(
+      '_plugin key must not have scopes',
+    );
+  });
+
+  it('rejects _internal key with scopes', async () => {
+    const configPath = writeConfig(tmpDir, {
+      ...VALID_CONFIG,
+      keys: {
+        ...VALID_CONFIG.keys,
+        _internal: { key: 'b'.repeat(64), scopes: ['/restricted'] },
+      },
+    });
+    await expect(loadConfig(configPath)).rejects.toThrow(
+      '_internal key must not have scopes',
+    );
+  });
+
+  it('accepts _plugin key without scopes', async () => {
+    const configPath = writeConfig(tmpDir, {
+      ...VALID_CONFIG,
+      keys: {
+        ...VALID_CONFIG.keys,
+        _plugin: 'c'.repeat(64),
+      },
+    });
+    const config = await loadConfig(configPath);
+    expect(config.resolvedKeys.find((k) => k.name === '_plugin')?.seed).toBe(
+      'c'.repeat(64),
+    );
+  });
+});
+
+describe('config singleton', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-config-'));
+    resetConfig();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    resetConfig();
+  });
+
+  it('throws if getConfig called before initConfig', () => {
+    expect(() => getConfig()).toThrow('Config not initialized');
+  });
+
+  it('initConfig populates getConfig', async () => {
+    const configPath = writeConfig(tmpDir, VALID_CONFIG);
+    await initConfig(configPath);
+    const config = getConfig();
+    expect(config.port).toBe(9999);
+  });
+
+  it('resetConfig clears the singleton', async () => {
+    const configPath = writeConfig(tmpDir, VALID_CONFIG);
+    await initConfig(configPath);
+    resetConfig();
+    expect(() => getConfig()).toThrow('Config not initialized');
+  });
+});

package/src/config/resolve.test.ts

@@ -0,0 +1,192 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  buildRuntimeConfig,
+  deriveInternalKey,
+  normalizeScopes,
+  resolveInsiders,
+  resolveKeys,
+  resolvePlantuml,
+} from './resolve.js';
+import type { JeevesConfig } from './schema.js';
+
+describe('normalizeScopes', () => {
+  it('returns null for undefined', () => {
+    expect(normalizeScopes(undefined)).toBe(null);
+  });
+
+  it('returns null for null', () => {
+    expect(normalizeScopes(null)).toBe(null);
+  });
+
+  it('wraps a string in allow array', () => {
+    expect(normalizeScopes('/docs')).toEqual({ allow: ['/docs'], deny: [] });
+  });
+
+  it('wraps an array as allow', () => {
+    expect(normalizeScopes(['/a', '/b'])).toEqual({
+      allow: ['/a', '/b'],
+      deny: [],
+    });
+  });
+
+  it('fills defaults for partial object', () => {
+    expect(normalizeScopes({ deny: ['/secret'] })).toEqual({
+      allow: ['/**'],
+      deny: ['/secret'],
+    });
+  });
+
+  it('passes through complete object', () => {
+    const scopes = { allow: ['/a'], deny: ['/b'] };
+    expect(normalizeScopes(scopes)).toEqual(scopes);
+  });
+});
+
+describe('resolveKeys', () => {
+  it('handles string key entries', () => {
+    const result = resolveKeys({ primary: 'seed123' });
+    expect(result).toEqual([
+      { name: 'primary', seed: 'seed123', scopes: null },
+    ]);
+  });
+
+  it('handles object key entries with scopes', () => {
+    const result = resolveKeys({
+      scoped: { key: 'seed456', scopes: ['/docs'] },
+    });
+    expect(result[0].name).toBe('scoped');
+    expect(result[0].seed).toBe('seed456');
+    expect(result[0].scopes).toEqual({ allow: ['/docs'], deny: [] });
+  });
+
+  it('handles mixed entries', () => {
+    const result = resolveKeys({
+      plain: 'abc',
+      complex: { key: 'def', scopes: { allow: ['/x'], deny: ['/y'] } },
+    });
+    expect(result).toHaveLength(2);
+    expect(result[0].scopes).toBe(null);
+    expect(result[1].scopes).toEqual({ allow: ['/x'], deny: ['/y'] });
+  });
+});
+
+describe('resolveInsiders', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jeeves-resolve-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('normalizes email to lowercase', () => {
+    const stateFile = path.join(tmpDir, 'state.json');
+    const result = resolveInsiders({ 'Test@Example.COM': {} }, stateFile);
+    expect(result[0].email).toBe('test@example.com');
+  });
+
+  it('merges state keys when available', () => {
+    const stateFile = path.join(tmpDir, 'state.json');
+    fs.writeFileSync(
+      stateFile,
+      JSON.stringify({
+        insiderKeys: {
+          'test@example.com': { seed: 'stateseed', createdAt: '2026-01-01' },
+        },
+      }),
+    );
+    const result = resolveInsiders({ 'test@example.com': {} }, stateFile);
+    expect(result[0].seed).toBe('stateseed');
+    expect(result[0].keyCreatedAt).toBe('2026-01-01');
+  });
+
+  it('returns empty seed when no state exists', () => {
+    const stateFile = path.join(tmpDir, 'state.json');
+    const result = resolveInsiders({ 'new@example.com': {} }, stateFile);
+    expect(result[0].seed).toBe('');
+    expect(result[0].keyCreatedAt).toBe(null);
+  });
+});
+
+describe('resolvePlantuml', () => {
+  it('appends community server as fallback', () => {
+    const result = resolvePlantuml();
+    expect(result.servers).toContain('https://www.plantuml.com/plantuml');
+  });
+
+  it('does not duplicate community server if already listed', () => {
+    const result = resolvePlantuml({
+      servers: ['https://www.plantuml.com/plantuml'],
+    });
+    expect(
+      result.servers.filter((s) => s === 'https://www.plantuml.com/plantuml'),
+    ).toHaveLength(1);
+  });
+
+  it('preserves configured servers before community', () => {
+    const result = resolvePlantuml({
+      servers: ['https://private.example.com'],
+    });
+    expect(result.servers[0]).toBe('https://private.example.com');
+    expect(result.servers[1]).toBe('https://www.plantuml.com/plantuml');
+  });
+
+  it('passes through jarPath and javaPath', () => {
+    const result = resolvePlantuml({
+      jarPath: '/opt/plantuml.jar',
+      javaPath: '/usr/bin/java',
+    });
+    expect(result.jarPath).toBe('/opt/plantuml.jar');
+    expect(result.javaPath).toBe('/usr/bin/java');
+  });
+});
+
+describe('deriveInternalKey', () => {
+  it('returns null when no _internal key exists', () => {
+    const keys = [{ name: 'primary', seed: 'abc', scopes: null }];
+    expect(deriveInternalKey(keys)).toBe(null);
+  });
+
+  it('derives a key from _internal seed', () => {
+    const keys = [{ name: '_internal', seed: 'x'.repeat(64), scopes: null }];
+    const result = deriveInternalKey(keys);
+    expect(result).toBeTypeOf('string');
+    expect(result!.length).toBeGreaterThan(0);
+  });
+});
+
+describe('buildRuntimeConfig', () => {
+  it('constructs correct path fields', () => {
+    const config = {
+      port: 1934,
+      eventTimeoutMs: 30000,
+      eventLogPurgeMs: 2592000000,
+      maxZipSizeMb: 100,
+      chromePath: '/usr/bin/chrome',
+      events: {},
+      auth: { modes: ['keys' as const] },
+      keys: { primary: 'a'.repeat(64) },
+      insiders: {},
+    } as JeevesConfig;
+
+    const result = buildRuntimeConfig(
+      config,
+      '/srv/jeeves',
+      '/srv/jeeves/config.json',
+    );
+    expect(result.stateFile).toBe(path.join('/srv/jeeves', 'state.json'));
+    expect(result.eventsLog).toBe(
+      path.join('/srv/jeeves', 'logs', 'webhook-events.jsonl'),
+    );
+    expect(result.configPath).toBe('/srv/jeeves/config.json');
+    expect(result.port).toBe(1934);
+    expect(result.authModes).toEqual(['keys']);
+  });
+});