@cyanautomation/kaseki-agent 1.4.1

package/src/kaseki-api-service-wrapper.ts

@@ -0,0 +1,188 @@
+/**
+ * Kaseki API Service - Express server wrapper
+ *
+ * Encapsulates the complete REST API service for async execution
+ */
+
+import express from 'express';
+import type { Server } from 'http';
+import { loadConfig } from './kaseki-api-config';
+import { JobScheduler } from './job-scheduler';
+import { WebhookManager } from './webhook-manager';
+import { IdempotencyStore } from './idempotency-store';
+import { PreFlightValidator } from './pre-flight-validator';
+import { createApiRouter } from './kaseki-api-routes';
+import { createEventLogger } from './logger';
+import { ResultCache } from './result-cache';
+import { createGracefulShutdown, assertSupportedNodeVersion } from './kaseki-api-service';
+
+interface KasekiAPIServiceOptions {
+  port?: number;
+  apiKeys?: string[];
+  logLevel?: string;
+}
+
+export class KasekiAPIServiceImpl {
+  private server: Server | null = null;
+  private logger = createEventLogger('kaseki-api');
+  private scheduler: JobScheduler | null = null;
+  private webhookManager: WebhookManager | null = null;
+  private idempotencyStore: IdempotencyStore | null = null;
+  private artifactCache: ResultCache | null = null;
+  private config = loadConfig();
+
+  constructor(options: KasekiAPIServiceOptions = {}) {
+    // Override config port if provided
+    if (options.port) {
+      this.config.port = options.port;
+    }
+
+    // Override log level if provided
+    if (options.logLevel) {
+      const validLevels: Record<string, 'debug' | 'info' | 'warn' | 'error'> = {
+        debug: 'debug',
+        info: 'info',
+        warn: 'warn',
+        error: 'error',
+      };
+      const level = validLevels[options.logLevel] || 'info';
+      this.config.logLevel = level;
+    }
+  }
+
+  /**
+   * Start the API service
+   */
+  async start(): Promise<void> {
+    try {
+      // Validate Node.js version
+      assertSupportedNodeVersion();
+
+      // Log startup configuration
+      this.logger.event('service_startup_config', {
+        port: this.config.port,
+        logLevel: this.config.logLevel,
+        maxConcurrentRuns: this.config.maxConcurrentRuns,
+        resultsDir: this.config.resultsDir,
+        nodeVersion: process.versions.node,
+      });
+
+      // Create Express app
+      const app = express();
+      app.use(express.json());
+
+      // Create managers
+      this.artifactCache = new ResultCache({
+        maxEntries: this.config.artifactCacheMaxEntries,
+        ttlMs: this.config.artifactCacheTtlMs,
+        maxFileBytes: this.config.artifactCacheMaxFileBytes,
+      });
+
+      this.webhookManager = new WebhookManager(this.config.resultsDir);
+      this.idempotencyStore = new IdempotencyStore(this.config.resultsDir, 24);
+      const preFlightValidator = new PreFlightValidator();
+
+      // Create scheduler
+      this.scheduler = new JobScheduler(
+        this.config,
+        this.webhookManager,
+        this.artifactCache
+      );
+
+      // Mount API routes
+      const apiRouter = createApiRouter(
+        this.scheduler,
+        this.config,
+        this.idempotencyStore,
+        preFlightValidator,
+        this.artifactCache
+      );
+      app.use('/api', apiRouter);
+      app.use('/', apiRouter);
+
+      // Start server
+      this.server = app.listen(this.config.port, () => {
+        this.logger.event('service_started', {
+          port: this.config.port,
+          logLevel: this.config.logLevel,
+          maxConcurrentRuns: this.config.maxConcurrentRuns,
+        });
+        console.log(`\n✓ Kaseki API service started on port ${this.config.port}`);
+        console.log(`  Health check: http://localhost:${this.config.port}/health`);
+        console.log(`  API routes: http://localhost:${this.config.port}/api/\n`);
+      });
+
+      // Setup graceful shutdown
+      if (this.server && this.scheduler && this.webhookManager && this.idempotencyStore) {
+        const gracefulShutdown = createGracefulShutdown({
+          server: this.server,
+          scheduler: this.scheduler,
+          webhookManager: this.webhookManager,
+          idempotencyStore: this.idempotencyStore,
+        });
+
+        process.on('SIGTERM', () => void gracefulShutdown('SIGTERM'));
+        process.on('SIGINT', () => void gracefulShutdown('SIGINT'));
+      }
+
+      // Catch unhandled errors
+      process.on('uncaughtException', (err) => {
+        this.logger.error('Uncaught exception:', {
+          error: String(err),
+          stack: err instanceof Error ? err.stack : undefined,
+        });
+        process.exit(1);
+      });
+
+      process.on('unhandledRejection', (reason) => {
+        this.logger.error('Unhandled rejection:', { reason: String(reason) });
+        process.exit(1);
+      });
+    } catch (error) {
+      this.logger.error('Failed to start service:', { error: String(error) });
+      throw error;
+    }
+  }
+
+  /**
+   * Stop the API service
+   */
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.server) {
+        this.server.close(() => {
+          this.logger.info('API service stopped');
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  /**
+   * Get service port
+   */
+  getPort(): number {
+    return this.config.port;
+  }
+
+  /**
+   * Get service status
+   */
+  getStatus(): {
+    running: boolean;
+    port: number;
+    uptime: number;
+    } {
+    return {
+      running: this.server?.listening ?? false,
+      port: this.config.port,
+      uptime: process.uptime(),
+    };
+  }
+}
+
+// Export both class name styles for compatibility
+export const KasekiAPIService = KasekiAPIServiceImpl;
+export default KasekiAPIServiceImpl;

package/src/kaseki-api-service.test.ts

@@ -0,0 +1,418 @@
+import * as fs from 'fs';
+import type { Server } from 'http';
+import { assertSupportedNodeVersion, createGracefulShutdown } from './kaseki-api-service';
+import { loadConfig } from './kaseki-api-config';
+import { JobScheduler } from './job-scheduler';
+import { WebhookManager } from './webhook-manager';
+import { RunRequestSchema } from './kaseki-api-types';
+
+describe('Kaseki API Configuration', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  test('loadConfig requires KASEKI_API_KEYS or KASEKI_API_KEYS_FILE', async () => {
+    delete process.env.KASEKI_API_KEYS;
+    delete process.env.KASEKI_API_KEYS_FILE;
+    process.env.KASEKI_RESULTS_DIR = '/tmp';
+
+    expect(() => loadConfig()).toThrow(/KASEKI_API_KEYS.*required/i);
+  });
+
+  test.each([
+    {
+      name: 'rejects non-numeric port string',
+      port: 'invalid',
+      expectedError: 'KASEKI_API_PORT must be a valid port number, got: invalid',
+    },
+    {
+      name: 'rejects zero port',
+      port: '0',
+      expectedError: 'KASEKI_API_PORT must be a valid port number, got: 0',
+    },
+    {
+      name: 'rejects negative port',
+      port: '-1',
+      expectedError: 'KASEKI_API_PORT must be a valid port number, got: -1',
+    },
+    {
+      name: 'rejects port above 65535',
+      port: '65536',
+      expectedError: 'KASEKI_API_PORT must be a valid port number, got: 65536',
+    },
+    {
+      name: 'accepts minimum valid port',
+      port: '1',
+      expectedPort: 1,
+    },
+    {
+      name: 'accepts maximum valid port',
+      port: '65535',
+      expectedPort: 65535,
+    },
+  ])('loadConfig port boundaries: $name', ({ port, expectedError, expectedPort }) => {
+    process.env.KASEKI_API_KEYS = 'test-key';
+    process.env.KASEKI_API_PORT = port;
+    process.env.KASEKI_RESULTS_DIR = '/tmp';
+
+    if (expectedError) {
+      expect(() => loadConfig()).toThrow(expectedError);
+      return;
+    }
+
+    const config = loadConfig();
+    expect(config.port).toBe(expectedPort);
+  });
+
+  describe.each([
+    {
+      name: 'parses numeric strings and trims comma-delimited API keys',
+      env: {
+        KASEKI_API_KEYS: ' key1 , key2 , key3 ',
+        KASEKI_API_PORT: '3001',
+        KASEKI_API_MAX_CONCURRENT_RUNS: '7',
+      },
+      expectedConfig: {
+        port: 3001,
+        apiKeys: ['key1', 'key2', 'key3'],
+        maxConcurrentRuns: 7,
+      },
+    },
+    {
+      name: 'accepts boundary max port and keeps defaults for omitted values',
+      env: {
+        KASEKI_API_KEYS: 'solo-key',
+        KASEKI_API_PORT: '65535',
+      },
+      expectedConfig: {
+        port: 65535,
+        apiKeys: ['solo-key'],
+        maxConcurrentRuns: 3,
+      },
+    },
+    {
+      name: 'uses default port when unset and normalizes sparse key list',
+      env: {
+        KASEKI_API_KEYS: 'alpha,, beta,   ,gamma ',
+      },
+      expectedConfig: {
+        port: 8080,
+        apiKeys: ['alpha', 'beta', 'gamma'],
+        maxConcurrentRuns: 3,
+      },
+    },
+  ])('loadConfig normalization: $name', ({ env, expectedConfig }) => {
+    delete process.env.KASEKI_API_PORT;
+    delete process.env.KASEKI_API_MAX_CONCURRENT_RUNS;
+    process.env.KASEKI_RESULTS_DIR = '/tmp';
+    Object.assign(process.env, env);
+
+    const config = loadConfig();
+
+    expect({
+      port: config.port,
+      apiKeys: config.apiKeys,
+      maxConcurrentRuns: config.maxConcurrentRuns,
+    }).toEqual(expectedConfig);
+  });
+
+  test('loadConfig parses API keys from file', async () => {
+    const keysFile = '/tmp/test-keys.txt';
+    fs.writeFileSync(keysFile, 'key1\n# comment\nkey2\n');
+
+    delete process.env.KASEKI_API_KEYS;
+    process.env.KASEKI_API_KEYS_FILE = keysFile;
+    process.env.KASEKI_RESULTS_DIR = '/tmp';
+
+    const config = loadConfig();
+    expect(config.apiKeys).toEqual(['key1', 'key2']);
+
+    fs.unlinkSync(keysFile);
+  });
+});
+
+describe('Kaseki API Request Validation', () => {
+  test.each([
+    {
+      name: 'accepts minimal required fields',
+      request: { repoUrl: 'https://github.com/org/repo', ref: 'main' },
+      expected: { repoUrl: 'https://github.com/org/repo', ref: 'main' },
+    },
+    {
+      name: 'applies default ref when omitted',
+      request: { repoUrl: 'https://github.com/org/repo' },
+      expected: { repoUrl: 'https://github.com/org/repo', ref: 'main' },
+    },
+    {
+      name: 'accepts startup check mode',
+      request: { repoUrl: 'https://github.com/org/repo', startupCheck: true },
+      expected: { repoUrl: 'https://github.com/org/repo', ref: 'main', startupCheck: true },
+    },
+    {
+      name: 'accepts explicit draft PR publishing mode',
+      request: { repoUrl: 'https://github.com/org/repo', publishMode: 'draft_pr' },
+      expected: { repoUrl: 'https://github.com/org/repo', ref: 'main', publishMode: 'draft_pr' },
+    },
+    {
+      name: 'accepts controller-style allowlist and validation aliases',
+      request: {
+        repoUrl: 'https://github.com/org/repo',
+        allowlist: { include: ['src/lib/parser.ts'] },
+        validation: { commands: ['npm test -- parser'] },
+      },
+      expected: {
+        repoUrl: 'https://github.com/org/repo',
+        ref: 'main',
+        allowlist: { include: ['src/lib/parser.ts'] },
+        validation: { commands: ['npm test -- parser'] },
+      },
+    },
+  ])('RunRequestSchema success cases: $name', ({ request, expected }) => {
+    const result = RunRequestSchema.parse(request);
+    expect(result).toMatchObject(expected);
+  });
+
+  test.each([
+    {
+      name: 'rejects invalid URL',
+      request: { repoUrl: 'not-a-url', ref: 'main' },
+      expectedIssue: {
+        path: ['repoUrl'],
+        messagePattern: /url/i,
+        value: 'not-a-url',
+      },
+    },
+    {
+      name: 'rejects invalid taskMode enum',
+      request: { repoUrl: 'https://github.com/org/repo', taskMode: 'invalid' },
+      expectedIssue: {
+        path: ['taskMode'],
+        messagePattern: /invalid (option|enum)|expected/i,
+        value: 'invalid',
+      },
+    },
+    {
+      name: 'rejects invalid publishMode enum',
+      request: { repoUrl: 'https://github.com/org/repo', publishMode: 'pr' },
+      expectedIssue: {
+        path: ['publishMode'],
+        messagePattern: /invalid (option|enum)|expected/i,
+        value: 'pr',
+      },
+    },
+  ])('RunRequestSchema rejects invalid payloads: $name', ({ request, expectedIssue }) => {
+    const result = RunRequestSchema.safeParse(request);
+
+    expect(result.success).toBe(false);
+    if (result.success) {
+      return;
+    }
+
+    const matchingIssue = result.error.issues.find((issue) =>
+      expectedIssue.path.every((segment, index) => issue.path[index] === segment),
+    );
+
+    expect(matchingIssue).toBeDefined();
+    expect(matchingIssue?.path).toEqual(expectedIssue.path);
+    expect(matchingIssue?.message).toMatch(expectedIssue.messagePattern);
+    const valueAtIssuePath = expectedIssue.path.reduce<any>((acc, segment) =>
+      (acc as any)?.[segment],
+      request as any,
+    );
+    expect(valueAtIssuePath).toBe(expectedIssue.value);
+  });
+});
+
+describe('Job Scheduler', () => {
+  let scheduler: JobScheduler;
+  let resultsDir: string;
+
+  beforeEach(() => {
+    resultsDir = fs.mkdtempSync('/tmp/kaseki-api-service-test-');
+    const config = {
+      port: 8080,
+      apiKeys: ['test-key'],
+      resultsDir,
+      maxConcurrentRuns: 2,
+      defaultTaskMode: 'patch' as const,
+      maxDiffBytes: 200000,
+      agentTimeoutSeconds: 1200,
+      logLevel: 'info' as const,
+    };
+
+    const webhookManager = new WebhookManager(resultsDir);
+    scheduler = new JobScheduler(config, webhookManager);
+  });
+
+  afterEach(() => {
+    scheduler.shutdown();
+    fs.rmSync(resultsDir, { recursive: true, force: true });
+  });
+
+  test('submitJob creates a queued job', async () => {
+    // Saturate scheduler concurrency so a newly submitted job remains queued.
+    (scheduler as any).running.add('existing-running-job');
+    (scheduler as any).running.add('second-existing-running-job');
+
+    const request = {
+      repoUrl: 'https://github.com/org/repo',
+      ref: 'main',
+    };
+
+    const submitted = await scheduler.submitJob(request);
+
+    // Contract outcome: job is queued when concurrency limit is reached.
+    expect(submitted.status).toBe('queued');
+    expect(submitted.request).toEqual(request);
+
+    // Contract outcome: queued job is visible via status and list/get endpoints.
+    expect(scheduler.getQueueStatus()).toEqual({
+      pending: 1,
+      running: 2,
+      maxConcurrent: 2,
+    });
+
+    const retrieved = scheduler.getJob(submitted.id);
+    const jobs = scheduler.listJobs();
+
+    expect(retrieved).toBeDefined();
+    expect(retrieved?.id).toBe(submitted.id);
+    expect(retrieved?.status).toBe('queued');
+    expect(jobs.some((job) => job.id === submitted.id && job.status === 'queued')).toBe(true);
+  });
+
+  test('submit/get/list keep job identity, request payload, and queue visibility coherent', async () => {
+    const request = {
+      repoUrl: 'https://github.com/org/repo',
+      ref: 'main',
+    };
+
+    const submitted = await scheduler.submitJob(request);
+    const retrieved = scheduler.getJob(submitted.id);
+    const jobs = scheduler.listJobs();
+
+    expect(retrieved).toBeDefined();
+    expect(retrieved?.id).toBe(submitted.id);
+    expect(retrieved?.request).toEqual(request);
+    expect(jobs).toHaveLength(1);
+    expect(jobs[0].id).toBe(submitted.id);
+    expect(jobs[0].request).toEqual(request);
+  });
+
+  test('listJobs returns all jobs sorted by creation time (newest first)', async () => {
+    const request1 = { repoUrl: 'https://github.com/org/repo1', ref: 'main' };
+    const request2 = { repoUrl: 'https://github.com/org/repo2', ref: 'main' };
+
+    await scheduler.submitJob(request1);
+    await scheduler.submitJob(request2);
+
+    const jobs = scheduler.listJobs();
+    expect(jobs.length).toBe(2);
+    expect(jobs[0].request.repoUrl).toBe(request2.repoUrl); // Newest first
+    expect(jobs[1].request.repoUrl).toBe(request1.repoUrl);
+  });
+
+  test('getQueueStatus reports pending and running count', async () => {
+    await scheduler.submitJob({ repoUrl: 'https://github.com/org/repo', ref: 'main' });
+
+    const status = scheduler.getQueueStatus();
+    expect(status).toEqual({
+      pending: 0,
+      running: 1,
+      maxConcurrent: 2,
+    });
+  });
+});
+
+describe('Kaseki API graceful shutdown', () => {
+  test('waits for server close before scheduler shutdown and exit', async () => {
+    const callOrder: string[] = [];
+    let closeCallback: ((err?: Error) => void) | undefined;
+
+    const server = {
+      close: jest.fn((cb: (err?: Error) => void) => {
+        closeCallback = cb;
+      }),
+    } as unknown as Server;
+
+    const scheduler = {
+      shutdown: jest.fn(() => {
+        callOrder.push('scheduler.shutdown');
+      }),
+    };
+
+    const webhookManager = {
+      shutdown: jest.fn(),
+    } as any;
+
+    const idempotencyStore = {
+      shutdown: jest.fn(),
+    } as any;
+
+    const exit = jest.fn((code: number) => {
+      callOrder.push(`exit:${code}`);
+      return undefined as never;
+    }) as unknown as (code: number) => never;
+
+    const gracefulShutdown = createGracefulShutdown({
+      server,
+      scheduler,
+      webhookManager,
+      idempotencyStore,
+      forceExitAfterMs: 1000,
+      exit,
+    });
+
+    const shutdownPromise = gracefulShutdown('SIGTERM');
+
+    expect(server.close).toHaveBeenCalledTimes(1);
+    expect(scheduler.shutdown).not.toHaveBeenCalled();
+    expect(exit).not.toHaveBeenCalled();
+
+    closeCallback?.();
+
+    await shutdownPromise;
+
+    expect(callOrder).toEqual(['scheduler.shutdown', 'exit:0']);
+  });
+});
+
+describe('Node runtime precheck', () => {
+  const originalExit = process.exit;
+
+  afterEach(() => {
+    process.exit = originalExit;
+    jest.restoreAllMocks();
+  });
+
+  test('allows supported Node major versions', async () => {
+    expect(() => assertSupportedNodeVersion('24.0.0')).not.toThrow();
+    expect(() => assertSupportedNodeVersion('25.1.2')).not.toThrow();
+  });
+
+  test.each(['x.y.z', '24.x.1', 'v24.0.0', '24.0.0-beta'])(
+    'exits early for malformed Node version string %s',
+    (version) => {
+      const exitMock = jest.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+        throw new Error(`exit:${code}`);
+      }) as never);
+
+      expect(() => assertSupportedNodeVersion(version)).toThrow('exit:1');
+      expect(exitMock).toHaveBeenCalledWith(1);
+    },
+  );
+  test('exits early for unsupported Node major versions', async () => {
+    const exitMock = jest.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    expect(() => assertSupportedNodeVersion('22.22.2')).toThrow('exit:1');
+    expect(exitMock).toHaveBeenCalledWith(1);
+  });
+});