@cyanautomation/kaseki-agent 1.4.1

package/dist/kaseki-cli-lib.d.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * kaseki-cli-lib.ts
+ *
+ * Core library for querying and analyzing kaseki instances.
+ * Provides functions for listing instances, reading status, detecting errors,
+ * and performing post-run analysis.
+ *
+ * Usage:
+ *   import { listInstances, getInstanceStatus } from './kaseki-cli-lib';
+ *   const instances = listInstances();
+ *   const status = getInstanceStatus('kaseki-1');
+ */
+import { Metadata, HostStart } from './instance-metadata-reader';
+import { deriveInstanceLifecycleStatus } from './instance-state-derivation';
+interface Config {
+    KASEKI_RESULTS_DIR: string;
+    KASEKI_RUNS_DIR: string;
+}
+interface KasekiInstance {
+    name: string;
+    status: 'running' | 'completed' | 'failed' | 'pending';
+    running: boolean;
+    exitCode: number | null;
+    elapsedSeconds: number | null;
+    stage: string;
+    model: string;
+    repo: string;
+    ref: string;
+}
+interface InstanceStatus {
+    instance?: string;
+    error?: {
+        kind: string;
+        message: string;
+    };
+    status?: 'running' | 'completed' | 'failed' | 'pending';
+    running?: boolean;
+    stage?: string;
+    elapsedSeconds?: number | null;
+    totalDurationSeconds?: number | null;
+    agentElapsedSeconds?: number | null;
+    timeoutSeconds?: number;
+    timeoutRiskPercent?: number;
+    timeoutImminent?: boolean;
+    timedOut?: boolean;
+    exitCode?: number | null;
+    failureClass?: string;
+    repo?: string;
+    ref?: string;
+    model?: string;
+}
+interface ProgressEvent {
+    timestamp?: string;
+    stage: string;
+    message: string;
+    malformed?: boolean;
+    [key: string]: any;
+}
+interface DetectedError {
+    severity: string;
+    source: string;
+    line: number;
+    message: string;
+}
+interface AnalysisResult {
+    instance?: string;
+    error?: {
+        kind: string;
+        message: string;
+    };
+    status?: string;
+    exit_code?: number | string;
+    failure_class?: string;
+    failed_command?: string;
+    validation_failed_command?: string;
+    duration_seconds?: number;
+    pi_duration_seconds?: number;
+    model?: string;
+    changed_files_count?: number;
+    changed_files?: string[];
+    tool_executions?: number;
+    errors?: DetectedError[];
+    error_count?: number;
+}
+declare const config: Config;
+declare const KASEKI_RESULTS_DIR: string;
+declare const KASEKI_RUNS_DIR: string;
+/**
+ * Parse docker ps --format '{{.Names}}' output into container name array.
+ */
+declare function parseDockerContainerNames(dockerNamesOutput: string): string[];
+/**
+ * Exact container-name matcher (test seam).
+ * Ensures "kaseki-1" does NOT match "kaseki-10".
+ */
+declare function isExactContainerNameMatch(containerName: string, instance: string): boolean;
+/**
+ * Check whether docker ps names output contains an exact instance match.
+ */
+declare function dockerNamesOutputHasInstance(dockerNamesOutput: string, instance: string): boolean;
+/**
+ * Determine if an instance is currently running as a Docker container.
+ * Gracefully falls back to false when Docker is unavailable.
+ */
+declare function isInstanceRunning(instance: string): boolean;
+/**
+ * Normalize an exit code candidate into an integer or null.
+ * (Re-exported from instance-state-derivation for backward compatibility)
+ */
+declare function normalizeExitCodeCandidate(value: any): number | null;
+/**
+ * Wrapper around resolveInstanceExitCode from instance-state-derivation.
+ * @deprecated Use the imported resolveInstanceExitCode directly.
+ * Kept for API compatibility; delegates to imported function.
+ */
+declare function resolveInstanceExitCodeLocal(resultDir: string, metadata?: Metadata): number | null;
+/**
+ * Wrapper around resolveInstanceStage from instance-state-derivation.
+ * Adapts the interface to match existing call sites.
+ * Note: The imported function requires resultsDir, but this wrapper uses the config.
+ */
+declare function resolveInstanceStageLocal(instance: string, metadata?: Metadata, fallback?: string): string;
+/**
+ * Wrapper around classifyFailure from instance-state-derivation.
+ * @deprecated Use the imported classifyFailure directly.
+ * Kept for API compatibility; delegates to imported function.
+ */
+declare function classifyFailureLocal(metadata?: Metadata, exitCode?: number | string | null): string;
+/**
+ * List all kaseki instances (running and completed).
+ * Returns array of instance objects with basic metadata.
+ */
+declare function listInstances(): KasekiInstance[];
+/**
+ * Read an artifact file from a kaseki results directory.
+ * Returns file contents as string, or null if not found.
+ */
+declare function readArtifact(instance: string, filename: string): string | null;
+/**
+ * Read a live-writable log file (tail the last N lines).
+ * Useful for stdout.log, stderr.log, validation.log which are continuously written.
+ */
+declare function readLiveLog(instance: string, filename: string, tailLines?: number): string | null;
+/**
+ * Read sanitized progress events emitted by the runner.
+ */
+declare function readProgressEvents(instance: string, tailLines?: number): ProgressEvent[] | null;
+/**
+ * Parse JSON artifact file.
+ * Returns parsed object, or empty object if not found or invalid.
+ */
+declare function readJsonArtifact(instance: string, filename: string): Record<string, any>;
+/**
+ * Get the current stage of a running or completed instance.
+ * Parses stdout.log for "==> stage_name" markers.
+ */
+declare function getCurrentStage(instance: string): string;
+/**
+ * Get the configured timeout seconds for the instance.
+ * Reads from host-start.json or falls back to default (1200).
+ */
+declare function getConfiguredTimeout(instance: string): number;
+/**
+ * Calculate timeout risk percentage (0-100).
+ * Returns 0 if no risk, 100 if timed out, or percentage if approaching timeout.
+ * Flags warning at 85% of timeout.
+ */
+declare function calculateTimeoutRiskPercent(instance: string, elapsedSeconds: number | null | undefined): number;
+/**
+ * Determine the overall status of an instance.
+ * Synthesizes all available state into a unified status object.
+ */
+declare function getInstanceStatus(instance: string): InstanceStatus;
+/**
+ * Error severity levels
+ */
+declare const ErrorSeverity: {
+    CRITICAL: string;
+    ERROR: string;
+    WARNING: string;
+};
+/**
+ * Centralized error pattern matchers.
+ * Used by detectErrors to identify error patterns in log files.
+ */
+declare const ERROR_PATTERNS: {
+    stderr: RegExp;
+    stderrExclude: RegExp;
+    validation: RegExp;
+};
+/**
+ * Scan a log file for lines matching an error pattern.
+ * @param instance The kaseki instance name
+ * @param artifactName The artifact filename to scan (e.g., 'stderr.log')
+ * @param pattern The regex pattern to match against each line
+ * @param source The error source label
+ * @param severity The error severity level
+ * @param excludePattern Optional regex to exclude certain lines
+ * @param exitCodeCondition Optional condition to check before scanning (e.g., secret_scan_exit_code !== 0)
+ * @returns Array of detected errors
+ */
+declare function scanLogForErrors(instance: string, artifactName: string, pattern: RegExp, source: string, severity: string, options?: {
+    excludePattern?: RegExp;
+    exitCodeCondition?: boolean;
+    allNonEmptyLines?: boolean;
+}): DetectedError[];
+/**
+ * Detect errors in a kaseki instance.
+ * Scans stderr, quality gates, secret scans, and validation failures.
+ */
+declare function detectErrors(instance: string): DetectedError[];
+/**
+ * Perform comprehensive post-run analysis.
+ * Returns aggregate metrics and diagnostics.
+ */
+declare function getAnalysis(instance: string): AnalysisResult;
+export { config, KASEKI_RESULTS_DIR, KASEKI_RUNS_DIR, listInstances, readArtifact, readLiveLog, readProgressEvents, readJsonArtifact, getCurrentStage, getConfiguredTimeout, calculateTimeoutRiskPercent, getInstanceStatus, detectErrors, scanLogForErrors, ERROR_PATTERNS, getAnalysis, ErrorSeverity, parseDockerContainerNames, isExactContainerNameMatch, dockerNamesOutputHasInstance, isInstanceRunning, deriveInstanceLifecycleStatus, normalizeExitCodeCandidate, resolveInstanceExitCodeLocal, resolveInstanceStageLocal, classifyFailureLocal, type Config, type KasekiInstance, type Metadata, type HostStart, type InstanceStatus, type ProgressEvent, type DetectedError, type AnalysisResult, };
+//# sourceMappingURL=kaseki-cli-lib.d.ts.map

package/dist/kaseki-cli-lib.d.ts.map

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