@cyanautomation/kaseki-agent 1.4.1

package/dist/utils/failure-artifact-writer.js

@@ -0,0 +1,157 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { StringDecoder } from 'node:string_decoder';
+/**
+ * Handles writing failure artifacts (failure.json, analysis.md, result-summary.md, etc.)
+ * when a job fails before complete diagnostics are available.
+ */
+export class FailureArtifactWriter {
+    resultsDir;
+    constructor(resultsDir) {
+        this.resultsDir = resultsDir;
+    }
+    /**
+     * Write API finalization artifacts when job fails before container diagnostics.
+     */
+    writeFailureArtifacts(job, cleanup, options) {
+        if (job.status !== 'failed' && !job.failureClass) {
+            return;
+        }
+        const resultDir = path.join(this.resultsDir, job.id);
+        const now = (job.completedAt || new Date()).toISOString();
+        try {
+            fs.mkdirSync(resultDir, { recursive: true });
+            this.writeFailureJson(resultDir, job, now, cleanup);
+            this.writeResultSummary(resultDir, job, now);
+            this.writeAnalysis(resultDir, job, now, cleanup, options?.lastStage);
+            this.writeMetadata(resultDir, job, now);
+            this.writeStderrLog(resultDir, job, options?.stdoutTail, options?.stderrTail);
+        }
+        catch {
+            // Best effort diagnostics; never mask the primary job failure.
+        }
+    }
+    writeFailureJson(resultDir, job, now, cleanup) {
+        const failurePath = path.join(resultDir, 'failure.json');
+        const shouldWriteFailure = !fs.existsSync(failurePath) || fs.statSync(failurePath).size === 0;
+        if (shouldWriteFailure) {
+            const payload = {
+                failureClass: job.failureClass || 'api_finalized',
+                error: job.error || 'Job failed before runner failure metadata was written',
+                exitCode: job.exitCode,
+                cancelledAt: job.failureClass === 'cancelled' ? now : undefined,
+                completedAt: now,
+                apiFinalized: true,
+                cleanup,
+            };
+            fs.writeFileSync(failurePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+        }
+    }
+    writeResultSummary(resultDir, job, now) {
+        const summaryPath = path.join(resultDir, 'result-summary.md');
+        const shouldWriteSummary = !fs.existsSync(summaryPath) || fs.statSync(summaryPath).size === 0;
+        if (shouldWriteSummary) {
+            fs.writeFileSync(summaryPath, [
+                `# ${job.id} failed`,
+                '',
+                `Failure class: ${job.failureClass || 'unknown'}`,
+                `Exit code: ${job.exitCode ?? 'unknown'}`,
+                `Error: ${job.error || 'unknown'}`,
+                `Completed at: ${now}`,
+                '',
+            ].join('\n'), 'utf-8');
+        }
+    }
+    writeAnalysis(resultDir, job, now, cleanup, lastStage) {
+        const analysisPath = path.join(resultDir, 'analysis.md');
+        const shouldWriteAnalysis = !fs.existsSync(analysisPath) || fs.statSync(analysisPath).size === 0;
+        if (shouldWriteAnalysis) {
+            fs.writeFileSync(analysisPath, [
+                `# Failure analysis for ${job.id}`,
+                '',
+                '## Completed work',
+                `- Job lifecycle entered: ${job.startedAt ? 'running' : 'queued'}`,
+                '- API finalization fallback written: yes',
+                '',
+                '## Failure classification',
+                `- Failure class: ${job.failureClass || 'unknown'}`,
+                `- Exit code: ${job.exitCode ?? 'unknown'}`,
+                `- Error: ${job.error || 'unknown'}`,
+                `- Last stage: ${lastStage || 'unknown'}`,
+                '',
+                '## Known warnings',
+                `- Container cleanup attempted: ${cleanup.attempted ? 'yes' : 'no'}`,
+                `- Container cleanup ok: ${cleanup.ok ? 'yes' : 'no'}`,
+                `- Cleanup detail: ${cleanup.detail || 'none'}`,
+                '',
+                `Completed at: ${now}`,
+                '',
+            ].join('\n'), 'utf-8');
+        }
+    }
+    writeMetadata(resultDir, job, now) {
+        const metadataPath = path.join(resultDir, 'metadata.json');
+        const shouldWriteMetadata = !fs.existsSync(metadataPath) || fs.statSync(metadataPath).size === 0;
+        if (shouldWriteMetadata) {
+            const startedAt = job.startedAt?.toISOString();
+            const completedAt = job.completedAt?.toISOString() || now;
+            const durationSeconds = job.startedAt && (job.completedAt || now)
+                ? Math.max(0, Math.round((new Date(completedAt).getTime() - job.startedAt.getTime()) / 1000))
+                : undefined;
+            const payload = {
+                id: job.id,
+                status: job.status,
+                timestamps: {
+                    createdAt: job.createdAt.toISOString(),
+                    startedAt,
+                    completedAt,
+                },
+                durations: {
+                    totalSeconds: durationSeconds,
+                },
+                runtime: {
+                    timeoutSeconds: job.effectiveTimeoutSeconds,
+                    pid: job.processId,
+                    nodeVersion: process.version,
+                    platform: process.platform,
+                },
+                env: {
+                    taskMode: job.request.taskMode,
+                    startupCheck: !!job.request.startupCheck,
+                },
+                failure: {
+                    failureClass: job.failureClass || 'api_finalized',
+                    error: job.error || 'Job failed before runner failure metadata was written',
+                    exitCode: job.exitCode,
+                },
+            };
+            fs.writeFileSync(metadataPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+        }
+    }
+    writeStderrLog(resultDir, job, stdoutTail, stderrTail) {
+        const stderrPath = path.join(resultDir, 'stderr.log');
+        const shouldWriteStderr = !fs.existsSync(stderrPath) || fs.statSync(stderrPath).size === 0;
+        if (shouldWriteStderr) {
+            const decodedStderr = stderrTail ? this.decodeUtf8Tail(stderrTail) : '';
+            const decodedStdout = stdoutTail ? this.decodeUtf8Tail(stdoutTail) : '';
+            const content = [
+                'stderr fallback generated by API finalization',
+                `failureClass=${job.failureClass || 'unknown'} exitCode=${job.exitCode ?? 'unknown'}`,
+                `error=${job.error || 'unknown'}`,
+                '',
+                decodedStderr ? '--- captured stderr tail ---' : '',
+                decodedStderr,
+                decodedStdout ? '--- captured stdout tail ---' : '',
+                decodedStdout,
+            ]
+                .filter(Boolean)
+                .join('\n');
+            fs.writeFileSync(stderrPath, `${content}\n`, 'utf-8');
+        }
+    }
+    decodeUtf8Tail(tail) {
+        const decoder = new StringDecoder('utf8');
+        return decoder.end(tail);
+    }
+}
+//# sourceMappingURL=failure-artifact-writer.js.map

package/dist/utils/failure-artifact-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-artifact-writer.js","sourceRoot":"","sources":["../../src/utils/failure-artifact-writer.ts"],"names":[],"mappings":"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"}

package/dist/utils/file-helpers.d.ts

@@ -0,0 +1,41 @@
+import * as fs from 'fs';
+/**
+ * Check if a file exists and is non-empty.
+ * Used for artifact availability checks.
+ */
+export declare function isNonEmptyFile(filePath: string): boolean;
+/**
+ * Read the first line of a file.
+ * Used for metadata extraction.
+ */
+export declare function readFirstLine(filePath: string): string | undefined;
+/**
+ * Read the tail of a file (last N lines).
+ * Used for log truncation.
+ */
+export declare function readTailLines(content: string, maxLines: number): string;
+/**
+ * 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 declare function readLastJsonlEvent(filePath: string, maxBytes?: number): Record<string, unknown> | 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 declare function commandOutput(command: string, args: string[], cwd?: string): string | undefined;
+/**
+ * Check if a file path exists.
+ */
+export declare function fileExists(filePath: string): boolean;
+/**
+ * Read a file's content as text, or return null if unavailable.
+ */
+export declare function readFileContent(filePath: string): string | null;
+/**
+ * Get file stats (size, modified time, etc.).
+ */
+export declare function getFileStats(filePath: string): fs.Stats | null;
+//# sourceMappingURL=file-helpers.d.ts.map

package/dist/utils/file-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/file-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AAGzB;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMxD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOlE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CA0D1G;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE/F;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAM9D"}

package/dist/utils/file-helpers.js

@@ -0,0 +1,143 @@
+import * as fs from 'fs';
+import { commandOutput as executeCommand } from '../lib/subprocess-helpers.js';
+/**
+ * Check if a file exists and is non-empty.
+ * Used for artifact availability checks.
+ */
+export function isNonEmptyFile(filePath) {
+    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) {
+    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, maxLines) {
+    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, maxBytes = 65536) {
+    if (maxBytes <= 0) {
+        return undefined;
+    }
+    let fd;
+    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);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : 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, args, cwd) {
+    return executeCommand(command, args, cwd);
+}
+/**
+ * Check if a file path exists.
+ */
+export function fileExists(filePath) {
+    try {
+        return fs.existsSync(filePath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a file's content as text, or return null if unavailable.
+ */
+export function readFileContent(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get file stats (size, modified time, etc.).
+ */
+export function getFileStats(filePath) {
+    try {
+        return fs.statSync(filePath);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=file-helpers.js.map

package/dist/utils/file-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-helpers.js","sourceRoot":"","sources":["../../src/utils/file-helpers.ts"],"names":[],"mappings":"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"}

package/dist/utils/http-client-factory.d.ts

@@ -0,0 +1,46 @@
+/**
+ * HTTP client factory for creating API requests with retry logic.
+ * Consolidates HTTP fetch + error handling patterns across kaseki-api-client.ts.
+ */
+export interface HttpRequestOptions {
+    method: 'GET' | 'POST' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: string;
+}
+export interface RetryConfig {
+    maxAttempts: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+}
+/**
+ * Creates an HTTP request factory with retry logic.
+ */
+export declare class HttpClientFactory {
+    private retryConfig;
+    constructor(retryConfig?: Partial<RetryConfig>);
+    /**
+     * Create and execute an HTTP request with automatic retry on failure.
+     */
+    request<T>(url: string, options: HttpRequestOptions, parser: (data: unknown) => T, description?: string): Promise<T>;
+    /**
+     * Create and execute an HTTP request that returns text content.
+     */
+    requestText(url: string, options: HttpRequestOptions, description?: string): Promise<string>;
+    /**
+     * Create and execute an HTTP request that returns binary data.
+     */
+    requestBlob(url: string, options: HttpRequestOptions, description?: string): Promise<Blob>;
+    /**
+     * Execute a function with exponential backoff retry.
+     */
+    private retryWithBackoff;
+    /**
+     * Parse error detail from a response body.
+     */
+    private parseErrorDetail;
+    /**
+     * Type guard for checking if a value is an object/record.
+     */
+    private isRecord;
+}
+//# sourceMappingURL=http-client-factory.d.ts.map

package/dist/utils/http-client-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client-factory.d.ts","sourceRoot":"","sources":["../../src/utils/http-client-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAWD;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,WAAW,CAAc;gBAErB,WAAW,GAAE,OAAO,CAAC,WAAW,CAAM;IAIlD;;OAEG;IACG,OAAO,CAAC,CAAC,EACb,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,EAC5B,WAAW,GAAE,MAAuB,GACnC,OAAO,CAAC,CAAC,CAAC;IAoBb;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,GAAE,MAAuB,GAAG,OAAO,CAAC,MAAM,CAAC;IAYlH;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,GAAE,MAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhH;;OAEG;YACW,gBAAgB;IA0C9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAGjB"}

package/dist/utils/http-client-factory.js

@@ -0,0 +1,114 @@
+/**
+ * HTTP client factory for creating API requests with retry logic.
+ * Consolidates HTTP fetch + error handling patterns across kaseki-api-client.ts.
+ */
+/**
+ * Default retry configuration for HTTP requests.
+ */
+const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 8000,
+};
+/**
+ * Creates an HTTP request factory with retry logic.
+ */
+export class HttpClientFactory {
+    retryConfig;
+    constructor(retryConfig = {}) {
+        this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...retryConfig };
+    }
+    /**
+     * Create and execute an HTTP request with automatic retry on failure.
+     */
+    async request(url, options, parser, description = 'HTTP request') {
+        return this.retryWithBackoff(async () => {
+            const response = await fetch(url, options);
+            if (!response.ok) {
+                let errorDetail;
+                try {
+                    const errorData = await response.json();
+                    errorDetail = this.parseErrorDetail(errorData);
+                }
+                catch {
+                    // Ignore non-JSON error payloads
+                }
+                throw new Error(`${description} failed: ${errorDetail ?? response.statusText}`);
+            }
+            const data = await response.json();
+            return parser(data);
+        }, description);
+    }
+    /**
+     * Create and execute an HTTP request that returns text content.
+     */
+    async requestText(url, options, description = 'HTTP request') {
+        return this.retryWithBackoff(async () => {
+            const response = await fetch(url, options);
+            if (!response.ok) {
+                throw new Error(`${description} failed: ${response.status}`);
+            }
+            return response.text();
+        }, description);
+    }
+    /**
+     * Create and execute an HTTP request that returns binary data.
+     */
+    async requestBlob(url, options, description = 'HTTP request') {
+        return this.retryWithBackoff(async () => {
+            const response = await fetch(url, options);
+            if (!response.ok) {
+                throw new Error(`${description} failed: ${response.status}`);
+            }
+            return response.blob();
+        }, description);
+    }
+    /**
+     * Execute a function with exponential backoff retry.
+     */
+    async retryWithBackoff(fn, description = 'Operation') {
+        let lastError;
+        for (let attempt = 0; attempt < this.retryConfig.maxAttempts; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry on 4xx errors (except 429 Too Many Requests)
+                const is4xxError = lastError.message.includes('400') ||
+                    lastError.message.includes('401') ||
+                    lastError.message.includes('403') ||
+                    lastError.message.includes('404');
+                if (is4xxError && !lastError.message.includes('429')) {
+                    throw lastError;
+                }
+                // If this is the last attempt, throw
+                if (attempt === this.retryConfig.maxAttempts - 1) {
+                    throw lastError;
+                }
+                // Calculate backoff with exponential increase
+                const delayMs = Math.min(this.retryConfig.initialDelayMs * Math.pow(2, attempt), this.retryConfig.maxDelayMs);
+                // Wait before retrying
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+            }
+        }
+        throw lastError || new Error(`${description} failed after ${this.retryConfig.maxAttempts} attempts`);
+    }
+    /**
+     * Parse error detail from a response body.
+     */
+    parseErrorDetail(value) {
+        if (!this.isRecord(value)) {
+            return undefined;
+        }
+        const detail = value.detail;
+        return typeof detail === 'string' ? detail : undefined;
+    }
+    /**
+     * Type guard for checking if a value is an object/record.
+     */
+    isRecord(value) {
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+}
+//# sourceMappingURL=http-client-factory.js.map

package/dist/utils/http-client-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client-factory.js","sourceRoot":"","sources":["../../src/utils/http-client-factory.ts"],"names":[],"mappings":"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"}

package/dist/utils/progress-normalizer.d.ts

@@ -0,0 +1,13 @@
+import { StructuredProgress } from '../kaseki-api-types';
+export declare function sanitizeProgressMessage(message: string): string;
+/**
+ * Normalize a progress event by ensuring common fields are standardized.
+ * Ensures message is populated from stage/detail, and timestamp is normalized to updatedAt.
+ */
+export declare function normalizeProgressEvent(event: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Convert a progress event to a StructuredProgress object.
+ * Always ensures stage is present; returns null only if event is invalid.
+ */
+export declare function toStructuredProgress(event: Record<string, unknown>, fallbackStage?: string): StructuredProgress | null;
+//# sourceMappingURL=progress-normalizer.d.ts.map

package/dist/utils/progress-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-normalizer.d.ts","sourceRoot":"","sources":["../../src/utils/progress-normalizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAKzD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB9F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,aAAa,GAAE,MAAkB,GAChC,kBAAkB,GAAG,IAAI,CAyB3B"}

package/dist/utils/progress-normalizer.js

@@ -0,0 +1,57 @@
+const SHELL_DIAGNOSTIC_PATTERN = /\/[^\s:]+(?:\/[^\s:]+)*:\s+line\s+\d+:\s+.*$/;
+const GIT_CLONE_STDERR_PATTERN = /Cloning into '[^']+'\.\.\.$/;
+export function sanitizeProgressMessage(message) {
+    return message
+        .replace(SHELL_DIAGNOSTIC_PATTERN, '')
+        .replace(GIT_CLONE_STDERR_PATTERN, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Normalize a progress event by ensuring common fields are standardized.
+ * Ensures message is populated from stage/detail, and timestamp is normalized to updatedAt.
+ */
+export function normalizeProgressEvent(event) {
+    const normalized = { ...event };
+    if (typeof normalized.stage === 'string') {
+        if (typeof normalized.message !== 'string' && typeof normalized.detail === 'string') {
+            normalized.message = sanitizeProgressMessage(normalized.detail);
+        }
+        if (typeof normalized.message !== 'string') {
+            normalized.message = normalized.stage;
+        }
+        else {
+            normalized.message = sanitizeProgressMessage(normalized.message);
+        }
+    }
+    if (typeof normalized.updatedAt !== 'string' && typeof normalized.timestamp === 'string') {
+        normalized.updatedAt = normalized.timestamp;
+    }
+    return normalized;
+}
+/**
+ * Convert a progress event to a StructuredProgress object.
+ * Always ensures stage is present; returns null only if event is invalid.
+ */
+export function toStructuredProgress(event, fallbackStage = 'running') {
+    const stage = typeof event.stage === 'string' ? event.stage.trim() : fallbackStage;
+    if (!stage) {
+        return null;
+    }
+    const message = typeof event.message === 'string'
+        ? sanitizeProgressMessage(event.message)
+        : typeof event.detail === 'string'
+            ? sanitizeProgressMessage(event.detail)
+            : undefined;
+    const numericPercent = typeof event.percentComplete === 'number' ? event.percentComplete : undefined;
+    const percentFromPercent = typeof event.percent === 'number' ? event.percent : undefined;
+    const percentComplete = numericPercent ?? percentFromPercent;
+    const updatedAt = typeof event.updatedAt === 'string' ? event.updatedAt : typeof event.timestamp === 'string' ? event.timestamp : undefined;
+    return {
+        stage,
+        percentComplete,
+        message: message || stage,
+        updatedAt,
+    };
+}
+//# sourceMappingURL=progress-normalizer.js.map

package/dist/utils/progress-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-normalizer.js","sourceRoot":"","sources":["../../src/utils/progress-normalizer.ts"],"names":[],"mappings":"AAEA,MAAM,wBAAwB,GAAG,8CAA8C,CAAC;AAChF,MAAM,wBAAwB,GAAG,6BAA6B,CAAC;AAE/D,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,OAAO,OAAO;SACX,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC;SACrC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC;SACrC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAA8B;IACnE,MAAM,UAAU,GAA4B,EAAE,GAAG,KAAK,EAAE,CAAC;IACzD,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACzC,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YACpF,UAAU,CAAC,OAAO,GAAG,uBAAuB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAClE,CAAC;QACD,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC3C,UAAU,CAAC,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,OAAO,GAAG,uBAAuB,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IACD,IAAI,OAAO,UAAU,CAAC,SAAS,KAAK,QAAQ,IAAI,OAAO,UAAU,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QACzF,UAAU,CAAC,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC;IAC9C,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAA8B,EAC9B,gBAAwB,SAAS;IAEjC,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;IACnF,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GACX,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAC/B,CAAC,CAAC,uBAAuB,CAAC,KAAK,CAAC,OAAO,CAAC;QACxC,CAAC,CAAC,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;YAChC,CAAC,CAAC,uBAAuB,CAAC,KAAK,CAAC,MAAM,CAAC;YACvC,CAAC,CAAC,SAAS,CAAC;IAElB,MAAM,cAAc,GAAG,OAAO,KAAK,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;IACrG,MAAM,kBAAkB,GAAG,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACzF,MAAM,eAAe,GAAG,cAAc,IAAI,kBAAkB,CAAC;IAC7D,MAAM,SAAS,GACb,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAE5H,OAAO;QACL,KAAK;QACL,eAAe;QACf,OAAO,EAAE,OAAO,IAAI,KAAK;QACzB,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/utils/response-helpers.d.ts

@@ -0,0 +1,34 @@
+import { Response } from 'express';
+import { StatusResponse } from '../kaseki-api-types';
+/**
+ * Send a standardized error response.
+ * Consolidates error response generation across all endpoints.
+ */
+export declare function sendErrorResponse(res: Response, status: number, title: string, detail: string): void;
+/**
+ * Build a StatusResponse from job metadata.
+ * Consolidates StatusResponse construction logic used in multiple routes.
+ */
+export declare function buildStatusResponse(jobData: {
+    id: string;
+    status: 'queued' | 'running' | 'completed' | 'failed';
+    exitCode?: number | null;
+    failureClass?: string | null;
+    correlationId?: string;
+    requestId?: string;
+    error?: string | null;
+    resultDir?: string;
+}): StatusResponse;
+/**
+ * Send a file response with appropriate headers for artifact delivery.
+ * Handles Content-Type detection and streaming.
+ */
+export declare function sendFileResponse(res: Response, filePath: string, fileName: string, options?: {
+    stream?: boolean;
+}): void;
+/**
+ * Detect Content-Type based on file extension.
+ * Used for artifact responses.
+ */
+export declare function detectContentType(fileName: string): string;
+//# sourceMappingURL=response-helpers.d.ts.map