@cyanautomation/kaseki-agent 1.4.1

package/src/utils/file-helpers.test.ts

@@ -0,0 +1,235 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  isNonEmptyFile,
+  readFirstLine,
+  readTailLines,
+  readLastJsonlEvent,
+  fileExists,
+  readFileContent,
+  getFileStats,
+  commandOutput,
+} from './file-helpers';
+
+describe('file-helpers', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-'));
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true });
+    }
+  });
+
+  describe('isNonEmptyFile', () => {
+    it('should return true for non-empty files', () => {
+      const filePath = path.join(tempDir, 'test.txt');
+      fs.writeFileSync(filePath, 'content');
+
+      expect(isNonEmptyFile(filePath)).toBe(true);
+    });
+
+    it('should keep empty-file coverage in the owning helper suite', () => {
+      const filePath = path.join(tempDir, 'empty.txt');
+      fs.writeFileSync(filePath, '');
+
+      expect(isNonEmptyFile(filePath)).toBe(false);
+    });
+
+    it('should return false for a missing file in the temporary test directory', () => {
+      const missingPath = path.join(tempDir, 'nonexistent.txt');
+
+      expect(fs.existsSync(tempDir)).toBe(true);
+      expect(fs.existsSync(missingPath)).toBe(false);
+      expect(isNonEmptyFile(missingPath)).toBe(false);
+    });
+  });
+
+  describe('readFirstLine', () => {
+    it('should read the first line of a file', () => {
+      const filePath = path.join(tempDir, 'multiline.txt');
+      fs.writeFileSync(filePath, 'first line\nsecond line\nthird line');
+
+      expect(readFirstLine(filePath)).toBe('first line');
+    });
+
+    it('should handle single-line files', () => {
+      const filePath = path.join(tempDir, 'single.txt');
+      fs.writeFileSync(filePath, 'only line');
+
+      expect(readFirstLine(filePath)).toBe('only line');
+    });
+
+    it('should trim whitespace from file boundaries', () => {
+      const filePath = path.join(tempDir, 'whitespace.txt');
+      fs.writeFileSync(filePath, '  trimmed  \nsecond');
+
+      // trim() applies to the whole file content, so it removes leading/trailing whitespace
+      // but the first line keeps its internal trailing spaces
+      expect(readFirstLine(filePath)).toBe('trimmed  ');
+    });
+
+    it('should return undefined for non-existent files', () => {
+      expect(readFirstLine(path.join(tempDir, 'nonexistent.txt'))).toBeUndefined();
+    });
+
+    it('should return undefined for empty files', () => {
+      const filePath = path.join(tempDir, 'empty.txt');
+      fs.writeFileSync(filePath, '');
+
+      expect(readFirstLine(filePath)).toBeUndefined();
+    });
+  });
+
+  describe('readTailLines', () => {
+    it('should return last N lines', () => {
+      const content = 'line1\nline2\nline3\nline4\nline5';
+
+      expect(readTailLines(content, 2)).toBe('line4\nline5');
+    });
+
+    it('should return all lines if content has fewer lines than requested', () => {
+      const content = 'line1\nline2\nline3';
+
+      expect(readTailLines(content, 5)).toBe(content);
+    });
+
+    it('should return empty string for maxLines <= 0', () => {
+      const content = 'line1\nline2\nline3';
+
+      expect(readTailLines(content, 0)).toBe('');
+      expect(readTailLines(content, -1)).toBe('');
+    });
+
+    it('should handle CRLF line endings', () => {
+      const content = 'line1\r\nline2\r\nline3\r\nline4';
+
+      // The function splits on /\r?\n/ which handles both CRLF and LF
+      // Then joins with \n, so CRLF is converted to LF in the output
+      expect(readTailLines(content, 2)).toBe('line3\nline4');
+    });
+  });
+
+  describe('readLastJsonlEvent', () => {
+    it('should parse a small single-line JSONL file', () => {
+      const filePath = path.join(tempDir, 'small.jsonl');
+      fs.writeFileSync(filePath, JSON.stringify({ stage: 'small', percentComplete: 10 }));
+
+      expect(readLastJsonlEvent(filePath)).toEqual({ stage: 'small', percentComplete: 10 });
+    });
+
+    it('should parse the last complete event from a large JSONL file without requiring the whole file', () => {
+      const filePath = path.join(tempDir, 'large.jsonl');
+      const filler = `${JSON.stringify({ stage: 'filler', message: 'x'.repeat(70000) })}\n`;
+      const lastEvent = { stage: 'large-tail', percentComplete: 99 };
+      fs.writeFileSync(filePath, `${filler}${JSON.stringify(lastEvent)}\n`);
+
+      expect(readLastJsonlEvent(filePath)).toEqual(lastEvent);
+    });
+
+    it('should ignore trailing newline characters and parse the previous event', () => {
+      const filePath = path.join(tempDir, 'trailing-newline.jsonl');
+      fs.writeFileSync(
+        filePath,
+        `${JSON.stringify({ stage: 'first' })}\n${JSON.stringify({ stage: 'second', percentComplete: 50 })}\n\n`
+      );
+
+      expect(readLastJsonlEvent(filePath)).toEqual({ stage: 'second', percentComplete: 50 });
+    });
+
+    it('should ignore a partial final line and parse the previous complete event', () => {
+      const filePath = path.join(tempDir, 'partial-final-line.jsonl');
+      fs.writeFileSync(filePath, `${JSON.stringify({ stage: 'complete', percentComplete: 75 })}\n{"stage":`);
+
+      expect(readLastJsonlEvent(filePath)).toEqual({ stage: 'complete', percentComplete: 75 });
+    });
+
+    it('should return undefined for malformed JSON on the final complete line', () => {
+      const filePath = path.join(tempDir, 'malformed.jsonl');
+      fs.writeFileSync(filePath, `${JSON.stringify({ stage: 'older' })}\n{not-json}\n`);
+
+      expect(readLastJsonlEvent(filePath)).toBeUndefined();
+    });
+
+    it('should return undefined for missing files', () => {
+      expect(readLastJsonlEvent(path.join(tempDir, 'missing.jsonl'))).toBeUndefined();
+    });
+  });
+
+  describe('fileExists', () => {
+    it('should return true for existing files', () => {
+      const filePath = path.join(tempDir, 'exists.txt');
+      fs.writeFileSync(filePath, 'content');
+
+      expect(fileExists(filePath)).toBe(true);
+    });
+
+    it('should return false for non-existent files', () => {
+      expect(fileExists(path.join(tempDir, 'nonexistent.txt'))).toBe(false);
+    });
+
+    it('should return true for existing directories', () => {
+      expect(fileExists(tempDir)).toBe(true);
+    });
+  });
+
+  describe('readFileContent', () => {
+    it('should read file content as text', () => {
+      const filePath = path.join(tempDir, 'content.txt');
+      fs.writeFileSync(filePath, 'hello world');
+
+      expect(readFileContent(filePath)).toBe('hello world');
+    });
+
+    it('should return null for non-existent files', () => {
+      expect(readFileContent(path.join(tempDir, 'nonexistent.txt'))).toBeNull();
+    });
+
+    it('should handle empty files', () => {
+      const filePath = path.join(tempDir, 'empty.txt');
+      fs.writeFileSync(filePath, '');
+
+      expect(readFileContent(filePath)).toBe('');
+    });
+  });
+
+  describe('getFileStats', () => {
+    it('should return file stats for existing files', () => {
+      const filePath = path.join(tempDir, 'test.txt');
+      fs.writeFileSync(filePath, 'content');
+
+      const stats = getFileStats(filePath);
+      expect(stats).not.toBeNull();
+      expect(stats?.size).toBe('content'.length);
+      expect(stats?.isFile()).toBe(true);
+    });
+
+    it('should return null for non-existent files', () => {
+      expect(getFileStats(path.join(tempDir, 'nonexistent.txt'))).toBeNull();
+    });
+
+    it('should work with directories', () => {
+      const stats = getFileStats(tempDir);
+      expect(stats).not.toBeNull();
+      expect(stats?.isDirectory()).toBe(true);
+    });
+  });
+
+  describe('commandOutput', () => {
+    it('returns trimmed output, undefined for unavailable output, and respects cwd', () => {
+      const runNode = (script: string, cwd?: string) =>
+        commandOutput(process.execPath, ['-e', script], cwd);
+
+      expect(runNode("console.log('  padded text  ')")).toBe('padded text');
+      expect(runNode('process.exit(1)')).toBeUndefined();
+      expect(runNode('process.exit(0)')).toBeUndefined();
+
+      const cwdScript = 'console.log(process.cwd())';
+      expect(runNode(cwdScript, tempDir)).not.toBe(runNode(cwdScript));
+    });
+  });
+});

package/src/utils/file-helpers.ts

@@ -0,0 +1,150 @@
+import * as fs from 'fs';
+import { commandOutput as executeCommand } from '../lib/subprocess-helpers';
+
+/**
+ * Check if a file exists and is non-empty.
+ * Used for artifact availability checks.
+ */
+export function isNonEmptyFile(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the first line of a file.
+ * Used for metadata extraction.
+ */
+export function readFirstLine(filePath: string): string | undefined {
+  try {
+    const value = fs.readFileSync(filePath, 'utf-8').trim().split(/\r?\n/)[0];
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read the tail of a file (last N lines).
+ * Used for log truncation.
+ */
+export function readTailLines(content: string, maxLines: number): string {
+  if (maxLines <= 0) {
+    return '';
+  }
+
+  const lines = content.split(/\r?\n/);
+  if (lines.length <= maxLines) {
+    return content;
+  }
+  return lines.slice(-maxLines).join('\n');
+}
+
+/**
+ * Read the final complete non-empty JSONL event from a file tail.
+ * Reads at most maxBytes from the end of the file so large progress logs do not
+ * need to be loaded fully for status responses.
+ */
+export function readLastJsonlEvent(filePath: string, maxBytes = 65536): Record<string, unknown> | undefined {
+  if (maxBytes <= 0) {
+    return undefined;
+  }
+
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(filePath, 'r');
+    const stats = fs.fstatSync(fd);
+    if (!stats.isFile() || stats.size === 0) {
+      return undefined;
+    }
+
+    const bytesToRead = Math.min(stats.size, maxBytes);
+    const start = stats.size - bytesToRead;
+    const buffer = Buffer.alloc(bytesToRead);
+    const bytesRead = fs.readSync(fd, buffer, 0, bytesToRead, start);
+    if (bytesRead <= 0) {
+      return undefined;
+    }
+
+    let tail = buffer.subarray(0, bytesRead).toString('utf-8');
+
+    const endsWithLineBreak = /[\r\n]$/.test(tail);
+    if (!endsWithLineBreak) {
+      const lastLineBreak = Math.max(tail.lastIndexOf('\n'), tail.lastIndexOf('\r'));
+      const shouldTreatOnlyLineAsComplete = start === 0 && lastLineBreak === -1;
+      if (!shouldTreatOnlyLineAsComplete) {
+        if (lastLineBreak === -1) {
+          return undefined;
+        }
+        tail = tail.slice(0, lastLineBreak + 1);
+      }
+    }
+
+    const lines = tail.split(/\r?\n/);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      const line = lines[index].trim();
+      if (!line) {
+        continue;
+      }
+
+      const parsed = JSON.parse(line) as unknown;
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+    }
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // Ignore close errors; callers treat the event as best-effort metadata.
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Execute a shell command and return its output.
+ * Delegates to subprocess-helpers for consolidated subprocess handling.
+ * Used for system diagnostics (e.g., git commands, docker info).
+ */
+export function commandOutput(command: string, args: string[], cwd?: string): string | undefined {
+  return executeCommand(command, args, cwd);
+}
+
+/**
+ * Check if a file path exists.
+ */
+export function fileExists(filePath: string): boolean {
+  try {
+    return fs.existsSync(filePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a file's content as text, or return null if unavailable.
+ */
+export function readFileContent(filePath: string): string | null {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get file stats (size, modified time, etc.).
+ */
+export function getFileStats(filePath: string): fs.Stats | null {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+}

package/src/utils/http-client-factory.test.ts

@@ -0,0 +1,245 @@
+import { HttpClientFactory, RetryConfig } from './http-client-factory';
+
+describe('http-client-factory', () => {
+  describe('HttpClientFactory', () => {
+    it('should retry transient fetch failures with the default retry config', async () => {
+      jest.useFakeTimers();
+      const originalFetch = global.fetch;
+      const jsonPayload = { id: 'run-123', status: 'ok' };
+      const fetchMock = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
+        .mockRejectedValueOnce(new Error('temporary network error'))
+        .mockRejectedValueOnce(new Error('upstream connection reset'))
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          statusText: 'OK',
+          json: jest.fn().mockResolvedValue(jsonPayload),
+        } as unknown as Response);
+      global.fetch = fetchMock;
+
+      try {
+        const requestPromise = new HttpClientFactory().request(
+          'https://api.example.test/json',
+          { method: 'GET' },
+          (data) => ({ runId: (data as typeof jsonPayload).id }),
+          'JSON request'
+        );
+
+        await Promise.resolve();
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+
+        await jest.advanceTimersByTimeAsync(1000);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+
+        await jest.advanceTimersByTimeAsync(2000);
+        await expect(requestPromise).resolves.toEqual({ runId: 'run-123' });
+        expect(fetchMock).toHaveBeenCalledTimes(3);
+        expect(fetchMock).toHaveBeenNthCalledWith(1, 'https://api.example.test/json', { method: 'GET' });
+        expect(fetchMock).toHaveBeenNthCalledWith(2, 'https://api.example.test/json', { method: 'GET' });
+        expect(fetchMock).toHaveBeenNthCalledWith(3, 'https://api.example.test/json', { method: 'GET' });
+      } finally {
+        global.fetch = originalFetch;
+        jest.useRealTimers();
+      }
+    });
+
+    it('should initialize with custom retry config', async () => {
+      jest.useFakeTimers();
+      const originalFetch = global.fetch;
+      const maxAttempts = 7;
+      const retryDelayMs = 25;
+      const customConfig: Partial<RetryConfig> = {
+        maxAttempts,
+        initialDelayMs: retryDelayMs,
+        maxDelayMs: retryDelayMs,
+      };
+      const fetchMock = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>();
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        fetchMock.mockRejectedValueOnce(new Error(`retryable outage ${attempt}`));
+      }
+      global.fetch = fetchMock;
+
+      try {
+        const requestPromise = new HttpClientFactory(customConfig).request(
+          'https://api.example.test/custom-retry',
+          { method: 'GET' },
+          (data) => data,
+          'Custom retry request'
+        );
+        const rejectionExpectation = expect(requestPromise).rejects.toThrow('retryable outage 7');
+
+        await Promise.resolve();
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+
+        for (let expectedCalls = 2; expectedCalls <= maxAttempts; expectedCalls++) {
+          await jest.advanceTimersByTimeAsync(retryDelayMs);
+          expect(fetchMock).toHaveBeenCalledTimes(expectedCalls);
+        }
+
+        await rejectionExpectation;
+        expect(fetchMock).toHaveBeenCalledTimes(maxAttempts);
+        expect(fetchMock).toHaveBeenLastCalledWith('https://api.example.test/custom-retry', { method: 'GET' });
+      } finally {
+        global.fetch = originalFetch;
+        jest.useRealTimers();
+      }
+    });
+
+    it('should return text payloads exactly and surface status-based requestText errors', async () => {
+      const factory = new HttpClientFactory({ maxAttempts: 3 });
+      const originalFetch = global.fetch;
+      const textPayload = 'plain text response\nwith exact whitespace and symbols: π ✓';
+      const successText = jest.fn().mockResolvedValue(textPayload);
+      const errorText = jest.fn().mockResolvedValue('not found body should not be read');
+      const fetchMock = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          statusText: 'OK',
+          text: successText,
+        } as unknown as Response)
+        .mockResolvedValueOnce({
+          ok: false,
+          status: 404,
+          statusText: 'Not Found',
+          text: errorText,
+        } as unknown as Response);
+      global.fetch = fetchMock;
+
+      try {
+        await expect(
+          factory.requestText('https://api.example.test/text', { method: 'POST', body: 'raw-body' }, 'Text request')
+        ).resolves.toBe(textPayload);
+        expect(successText).toHaveBeenCalledTimes(1);
+
+        await expect(
+          factory.requestText('https://api.example.test/missing-text', { method: 'GET' }, 'Missing text request')
+        ).rejects.toThrow('Missing text request failed: 404');
+        expect(errorText).not.toHaveBeenCalled();
+
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(fetchMock).toHaveBeenNthCalledWith(1, 'https://api.example.test/text', {
+          method: 'POST',
+          body: 'raw-body',
+        });
+        expect(fetchMock).toHaveBeenNthCalledWith(2, 'https://api.example.test/missing-text', { method: 'GET' });
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('should return blob payloads from requestBlob', async () => {
+      const factory = new HttpClientFactory({ maxAttempts: 1 });
+      const originalFetch = global.fetch;
+      const blobText = 'known blob payload';
+      const blobPayload = new Blob([blobText], { type: 'text/plain' });
+      const blobResponse = jest.fn().mockResolvedValue(blobPayload);
+      const fetchMock = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>().mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        blob: blobResponse,
+      } as unknown as Response);
+      global.fetch = fetchMock;
+
+      try {
+        const result = await factory.requestBlob(
+          'https://api.example.test/blob',
+          { method: 'GET', headers: { Accept: 'text/plain' } },
+          'Blob request'
+        );
+
+        expect(result.type).toBe('text/plain');
+        expect(result.size).toBe(blobPayload.size);
+        await expect(result.text()).resolves.toBe(blobText);
+        expect(blobResponse).toHaveBeenCalledTimes(1);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(fetchMock).toHaveBeenCalledWith('https://api.example.test/blob', {
+          method: 'GET',
+          headers: { Accept: 'text/plain' },
+        });
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+
+    it('should handle successful requests with proper parsing and JSON request error semantics', async () => {
+      const factory = new HttpClientFactory({ maxAttempts: 1 });
+      const originalFetch = global.fetch;
+      const jsonPayload = { id: 'run-123', nested: { status: 'ok' } };
+      const jsonErrorPayload = { detail: 'invalid run id' };
+      const textPayload = 'plain text response';
+      const blobPayload = new Blob(['binary response'], { type: 'application/octet-stream' });
+      const successJson = jest.fn().mockResolvedValue(jsonPayload);
+      const errorJson = jest.fn().mockResolvedValue(jsonErrorPayload);
+      const fetchMock = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          statusText: 'OK',
+          json: successJson,
+        } as unknown as Response)
+        .mockResolvedValueOnce({
+          ok: false,
+          status: 400,
+          statusText: 'Bad Request',
+          json: errorJson,
+        } as unknown as Response)
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          statusText: 'OK',
+          text: jest.fn().mockResolvedValue(textPayload),
+        } as unknown as Response)
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          statusText: 'OK',
+          blob: jest.fn().mockResolvedValue(blobPayload),
+        } as unknown as Response);
+      global.fetch = fetchMock;
+
+      try {
+        await expect(
+          factory.request(
+            'https://api.example.test/json',
+            { method: 'GET' },
+            (data) => {
+              expect(data).toEqual(jsonPayload);
+              return { runId: (data as typeof jsonPayload).id, status: (data as typeof jsonPayload).nested.status };
+            },
+            'JSON request'
+          )
+        ).resolves.toEqual({ runId: 'run-123', status: 'ok' });
+        expect(successJson).toHaveBeenCalledTimes(1);
+
+        await expect(
+          factory.request(
+            'https://api.example.test/json-error',
+            { method: 'POST', body: '{"id":"missing"}' },
+            (data) => data,
+            'JSON request'
+          )
+        ).rejects.toThrow('JSON request failed: invalid run id');
+        expect(errorJson).toHaveBeenCalledTimes(1);
+
+        await expect(
+          factory.requestText('https://api.example.test/text', { method: 'POST', body: '{}' }, 'Text request')
+        ).resolves.toBe(textPayload);
+        await expect(
+          factory.requestBlob('https://api.example.test/blob', { method: 'DELETE' }, 'Blob request')
+        ).resolves.toBe(blobPayload);
+
+        expect(fetchMock).toHaveBeenNthCalledWith(1, 'https://api.example.test/json', { method: 'GET' });
+        expect(fetchMock).toHaveBeenNthCalledWith(2, 'https://api.example.test/json-error', {
+          method: 'POST',
+          body: '{"id":"missing"}',
+        });
+        expect(fetchMock).toHaveBeenNthCalledWith(3, 'https://api.example.test/text', { method: 'POST', body: '{}' });
+        expect(fetchMock).toHaveBeenNthCalledWith(4, 'https://api.example.test/blob', { method: 'DELETE' });
+      } finally {
+        global.fetch = originalFetch;
+      }
+    });
+  });
+});