@curl-runner/cli 1.14.0 → 1.16.0

package/src/diff/response-differ.ts

@@ -0,0 +1,489 @@
+import type {
+  Baseline,
+  DiffCompareResult,
+  DiffConfig,
+  DiffSummary,
+  ExecutionResult,
+  GlobalDiffConfig,
+  JsonValue,
+  ResponseDiff,
+} from '../types/config';
+import { BaselineManager } from './baseline-manager';
+
+/**
+ * Compares responses against baselines with support for exclusions and match rules.
+ */
+export class ResponseDiffer {
+  private excludePaths: Set<string>;
+  private matchRules: Map<string, string>;
+  private includeTimings: boolean;
+
+  constructor(config: DiffConfig) {
+    this.excludePaths = new Set(config.exclude || []);
+    this.matchRules = new Map(Object.entries(config.match || {}));
+    this.includeTimings = config.includeTimings || false;
+  }
+
+  /**
+   * Compares current response against baseline.
+   */
+  compare(
+    baseline: Baseline,
+    current: Baseline,
+    baselineLabel: string,
+    currentLabel: string,
+    requestName: string,
+  ): DiffCompareResult {
+    const differences: ResponseDiff[] = [];
+
+    // Compare status
+    if (baseline.status !== undefined || current.status !== undefined) {
+      if (baseline.status !== current.status && !this.isExcluded('status')) {
+        differences.push({
+          path: 'status',
+          baseline: baseline.status,
+          current: current.status,
+          type: 'changed',
+        });
+      }
+    }
+
+    // Compare headers
+    if (baseline.headers || current.headers) {
+      const headerDiffs = this.compareObjects(
+        baseline.headers || {},
+        current.headers || {},
+        'headers',
+      );
+      differences.push(...headerDiffs);
+    }
+
+    // Compare body
+    if (baseline.body !== undefined || current.body !== undefined) {
+      const bodyDiffs = this.deepCompare(baseline.body, current.body, 'body');
+      differences.push(...bodyDiffs);
+    }
+
+    const result: DiffCompareResult = {
+      requestName,
+      hasDifferences: differences.length > 0,
+      isNewBaseline: false,
+      baselineLabel,
+      currentLabel,
+      differences,
+    };
+
+    // Add timing diff if enabled
+    if (this.includeTimings && baseline.timing !== undefined && current.timing !== undefined) {
+      const changePercent = ((current.timing - baseline.timing) / baseline.timing) * 100;
+      result.timingDiff = {
+        baseline: baseline.timing,
+        current: current.timing,
+        changePercent,
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * Deep comparison of two values with path tracking.
+   */
+  deepCompare(baseline: unknown, current: unknown, path: string): ResponseDiff[] {
+    if (this.isExcluded(path)) {
+      return [];
+    }
+
+    if (this.matchesRule(path, current)) {
+      return [];
+    }
+
+    if (baseline === null && current === null) {
+      return [];
+    }
+    if (baseline === undefined && current === undefined) {
+      return [];
+    }
+
+    const baselineType = this.getType(baseline);
+    const currentType = this.getType(current);
+
+    if (baselineType !== currentType) {
+      return [
+        {
+          path,
+          baseline,
+          current,
+          type: 'type_mismatch',
+        },
+      ];
+    }
+
+    if (baselineType !== 'object' && baselineType !== 'array') {
+      if (baseline !== current) {
+        return [
+          {
+            path,
+            baseline,
+            current,
+            type: 'changed',
+          },
+        ];
+      }
+      return [];
+    }
+
+    if (baselineType === 'array') {
+      return this.compareArrays(baseline as JsonValue[], current as JsonValue[], path);
+    }
+
+    return this.compareObjects(
+      baseline as Record<string, unknown>,
+      current as Record<string, unknown>,
+      path,
+    );
+  }
+
+  /**
+   * Compares two arrays.
+   */
+  private compareArrays(baseline: JsonValue[], current: JsonValue[], path: string): ResponseDiff[] {
+    const differences: ResponseDiff[] = [];
+    const maxLen = Math.max(baseline.length, current.length);
+
+    for (let i = 0; i < maxLen; i++) {
+      const itemPath = `${path}[${i}]`;
+
+      if (i >= baseline.length) {
+        if (!this.isExcluded(itemPath)) {
+          differences.push({
+            path: itemPath,
+            baseline: undefined,
+            current: current[i],
+            type: 'added',
+          });
+        }
+      } else if (i >= current.length) {
+        if (!this.isExcluded(itemPath)) {
+          differences.push({
+            path: itemPath,
+            baseline: baseline[i],
+            current: undefined,
+            type: 'removed',
+          });
+        }
+      } else {
+        const itemDiffs = this.deepCompare(baseline[i], current[i], itemPath);
+        differences.push(...itemDiffs);
+      }
+    }
+
+    return differences;
+  }
+
+  /**
+   * Compares two objects.
+   */
+  private compareObjects(
+    baseline: Record<string, unknown>,
+    current: Record<string, unknown>,
+    path: string,
+  ): ResponseDiff[] {
+    const differences: ResponseDiff[] = [];
+    const allKeys = new Set([...Object.keys(baseline), ...Object.keys(current)]);
+
+    for (const key of allKeys) {
+      const keyPath = path ? `${path}.${key}` : key;
+      const hasBaseline = key in baseline;
+      const hasCurrent = key in current;
+
+      if (!hasBaseline && hasCurrent) {
+        if (!this.isExcluded(keyPath)) {
+          differences.push({
+            path: keyPath,
+            baseline: undefined,
+            current: current[key],
+            type: 'added',
+          });
+        }
+      } else if (hasBaseline && !hasCurrent) {
+        if (!this.isExcluded(keyPath)) {
+          differences.push({
+            path: keyPath,
+            baseline: baseline[key],
+            current: undefined,
+            type: 'removed',
+          });
+        }
+      } else {
+        const keyDiffs = this.deepCompare(baseline[key], current[key], keyPath);
+        differences.push(...keyDiffs);
+      }
+    }
+
+    return differences;
+  }
+
+  /**
+   * Checks if a path should be excluded from comparison.
+   */
+  isExcluded(path: string): boolean {
+    if (this.excludePaths.has(path)) {
+      return true;
+    }
+
+    for (const pattern of this.excludePaths) {
+      if (pattern.startsWith('*.')) {
+        const suffix = pattern.slice(2);
+        if (path.endsWith(`.${suffix}`)) {
+          return true;
+        }
+        const lastPart = path.split('.').pop();
+        if (lastPart === suffix) {
+          return true;
+        }
+      }
+
+      if (pattern.includes('[*]')) {
+        const regex = new RegExp(
+          `^${pattern.replace(/\[\*\]/g, '\\[\\d+\\]').replace(/\./g, '\\.')}$`,
+        );
+        if (regex.test(path)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Checks if a value matches a custom rule for its path.
+   */
+  matchesRule(path: string, value: unknown): boolean {
+    const rule = this.matchRules.get(path);
+    if (!rule) {
+      return false;
+    }
+
+    if (rule === '*') {
+      return true;
+    }
+
+    if (rule.startsWith('regex:')) {
+      const pattern = rule.slice(6);
+      try {
+        const regex = new RegExp(pattern);
+        return regex.test(String(value));
+      } catch {
+        return false;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Gets the type of a value for comparison.
+   */
+  private getType(value: unknown): string {
+    if (value === null) {
+      return 'null';
+    }
+    if (value === undefined) {
+      return 'undefined';
+    }
+    if (Array.isArray(value)) {
+      return 'array';
+    }
+    return typeof value;
+  }
+}
+
+/**
+ * Orchestrates response diffing between runs.
+ */
+export class DiffOrchestrator {
+  private manager: BaselineManager;
+
+  constructor(globalConfig: GlobalDiffConfig = {}) {
+    this.manager = new BaselineManager(globalConfig);
+  }
+
+  /**
+   * Compares execution results against a baseline.
+   */
+  async compareWithBaseline(
+    yamlPath: string,
+    results: ExecutionResult[],
+    currentLabel: string,
+    baselineLabel: string,
+    config: DiffConfig,
+  ): Promise<DiffSummary> {
+    const baselineFile = await this.manager.load(yamlPath, baselineLabel);
+    const diffResults: DiffCompareResult[] = [];
+
+    for (const result of results) {
+      if (result.skipped || !result.success) {
+        continue;
+      }
+
+      const requestName = result.request.name || result.request.url;
+      const currentBaseline = this.manager.createBaseline(result, config);
+
+      if (!baselineFile) {
+        // No baseline exists - mark as new
+        diffResults.push({
+          requestName,
+          hasDifferences: false,
+          isNewBaseline: true,
+          baselineLabel,
+          currentLabel,
+          differences: [],
+        });
+        continue;
+      }
+
+      const storedBaseline = baselineFile.baselines[requestName];
+
+      if (!storedBaseline) {
+        // Request not in baseline - mark as new
+        diffResults.push({
+          requestName,
+          hasDifferences: false,
+          isNewBaseline: true,
+          baselineLabel,
+          currentLabel,
+          differences: [],
+        });
+        continue;
+      }
+
+      const differ = new ResponseDiffer(config);
+      const compareResult = differ.compare(
+        storedBaseline,
+        currentBaseline,
+        baselineLabel,
+        currentLabel,
+        requestName,
+      );
+      diffResults.push(compareResult);
+    }
+
+    return {
+      totalRequests: diffResults.length,
+      unchanged: diffResults.filter((r) => !r.hasDifferences && !r.isNewBaseline).length,
+      changed: diffResults.filter((r) => r.hasDifferences).length,
+      newBaselines: diffResults.filter((r) => r.isNewBaseline).length,
+      results: diffResults,
+    };
+  }
+
+  /**
+   * Compares two stored baselines (offline comparison).
+   */
+  async compareTwoBaselines(
+    yamlPath: string,
+    label1: string,
+    label2: string,
+    config: DiffConfig,
+  ): Promise<DiffSummary> {
+    const file1 = await this.manager.load(yamlPath, label1);
+    const file2 = await this.manager.load(yamlPath, label2);
+
+    if (!file1) {
+      throw new Error(`Baseline '${label1}' not found`);
+    }
+    if (!file2) {
+      throw new Error(`Baseline '${label2}' not found`);
+    }
+
+    const allRequestNames = new Set([
+      ...Object.keys(file1.baselines),
+      ...Object.keys(file2.baselines),
+    ]);
+
+    const diffResults: DiffCompareResult[] = [];
+    const differ = new ResponseDiffer(config);
+
+    for (const requestName of allRequestNames) {
+      const baseline1 = file1.baselines[requestName];
+      const baseline2 = file2.baselines[requestName];
+
+      if (!baseline1) {
+        diffResults.push({
+          requestName,
+          hasDifferences: true,
+          isNewBaseline: false,
+          baselineLabel: label1,
+          currentLabel: label2,
+          differences: [
+            {
+              path: '',
+              baseline: undefined,
+              current: 'exists',
+              type: 'added',
+            },
+          ],
+        });
+        continue;
+      }
+
+      if (!baseline2) {
+        diffResults.push({
+          requestName,
+          hasDifferences: true,
+          isNewBaseline: false,
+          baselineLabel: label1,
+          currentLabel: label2,
+          differences: [
+            {
+              path: '',
+              baseline: 'exists',
+              current: undefined,
+              type: 'removed',
+            },
+          ],
+        });
+        continue;
+      }
+
+      const compareResult = differ.compare(baseline1, baseline2, label1, label2, requestName);
+      diffResults.push(compareResult);
+    }
+
+    return {
+      totalRequests: diffResults.length,
+      unchanged: diffResults.filter((r) => !r.hasDifferences).length,
+      changed: diffResults.filter((r) => r.hasDifferences).length,
+      newBaselines: 0,
+      results: diffResults,
+    };
+  }
+
+  /**
+   * Saves current results as baseline.
+   */
+  async saveBaseline(
+    yamlPath: string,
+    label: string,
+    results: ExecutionResult[],
+    config: DiffConfig,
+  ): Promise<void> {
+    await this.manager.saveBaseline(yamlPath, label, results, config);
+  }
+
+  /**
+   * Lists available baseline labels.
+   */
+  async listLabels(yamlPath: string): Promise<string[]> {
+    return this.manager.listLabels(yamlPath);
+  }
+
+  /**
+   * Gets the baseline manager instance.
+   */
+  getManager(): BaselineManager {
+    return this.manager;
+  }
+}

package/src/parser/yaml.ts

@@ -1,4 +1,3 @@
-import { YAML } from 'bun';
 import type { RequestConfig, ResponseStoreContext, YamlFile } from '../types/config';
 
 // Using class for organization, but could be refactored to functions
@@ -6,11 +5,11 @@ export class YamlParser {
   static async parseFile(filepath: string): Promise<YamlFile> {
     const file = Bun.file(filepath);
     const content = await file.text();
-    return YAML.parse(content) as YamlFile;
+    return Bun.YAML.parse(content) as YamlFile;
   }
 
   static parse(content: string): YamlFile {
-    return YAML.parse(content) as YamlFile;
+    return Bun.YAML.parse(content) as YamlFile;
   }
 
   /**

package/src/types/bun-yaml.d.ts

@@ -0,0 +1,11 @@
+// Type declarations for Bun.YAML which is not in bun-types
+declare global {
+  namespace Bun {
+    const YAML: {
+      parse(content: string): unknown;
+      stringify(value: unknown): string;
+    };
+  }
+}
+
+export {};

package/src/types/config.ts

@@ -257,6 +257,11 @@ export interface RequestConfig {
    * Use `true` to enable with defaults, or provide detailed config.
    */
   snapshot?: SnapshotConfig | boolean;
+  /**
+   * Response diffing configuration for this request.
+   * Use `true` to enable with defaults, or provide detailed config.
+   */
+  diff?: DiffConfig | boolean;
   sourceOutputConfig?: {
     verbose?: boolean;
     showHeaders?: boolean;
@@ -335,6 +340,11 @@ export interface GlobalConfig {
    * Saves response snapshots and compares future runs against them.
    */
   snapshot?: GlobalSnapshotConfig;
+  /**
+   * Response diffing configuration.
+   * Compare responses between environments or runs to detect API drift.
+   */
+  diff?: GlobalDiffConfig;
   variables?: Record<string, string>;
   output?: {
     verbose?: boolean;
@@ -374,6 +384,8 @@ export interface ExecutionResult {
   };
   /** Snapshot comparison result (if snapshot testing enabled). */
   snapshotResult?: SnapshotCompareResult;
+  /** Diff comparison result (if response diffing enabled). */
+  diffResult?: DiffCompareResult;
   /** Whether this request was skipped due to a `when` condition. */
   skipped?: boolean;
   /** Reason the request was skipped (condition that failed). */
@@ -534,3 +546,93 @@ export interface SnapshotCompareResult {
   updated: boolean;
   differences: SnapshotDiff[];
 }
+
+/**
+ * Configuration for response diffing at request level.
+ */
+export interface DiffConfig {
+  /** Enable diffing for this request. */
+  enabled?: boolean;
+  /** Paths to exclude from comparison (e.g., 'body.timestamp'). */
+  exclude?: string[];
+  /** Match rules for dynamic values (path -> '*' or 'regex:pattern'). */
+  match?: Record<string, string>;
+  /** Include timing differences in comparison. Default: false */
+  includeTimings?: boolean;
+}
+
+/**
+ * Global configuration for response diffing.
+ */
+export interface GlobalDiffConfig extends DiffConfig {
+  /** Directory for baseline files. Default: '__baselines__' */
+  dir?: string;
+  /** Label for current run (e.g., 'staging', 'production'). */
+  label?: string;
+  /** Label to compare against. */
+  compareWith?: string;
+  /** Save current run as baseline. */
+  save?: boolean;
+  /** Output format for diff results. Default: 'terminal' */
+  outputFormat?: 'terminal' | 'json' | 'markdown';
+}
+
+/**
+ * Stored baseline data for a single request.
+ */
+export interface Baseline {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: JsonValue;
+  timing?: number;
+  hash: string;
+  capturedAt: string;
+}
+
+/**
+ * Baseline file format.
+ */
+export interface BaselineFile {
+  version: number;
+  label: string;
+  capturedAt: string;
+  baselines: Record<string, Baseline>;
+}
+
+/**
+ * Single difference in response comparison.
+ */
+export interface ResponseDiff {
+  path: string;
+  baseline: unknown;
+  current: unknown;
+  type: 'added' | 'removed' | 'changed' | 'type_mismatch';
+}
+
+/**
+ * Result of comparing a response against a baseline.
+ */
+export interface DiffCompareResult {
+  requestName: string;
+  hasDifferences: boolean;
+  isNewBaseline: boolean;
+  baselineLabel: string;
+  currentLabel: string;
+  differences: ResponseDiff[];
+  timingDiff?: {
+    baseline: number;
+    current: number;
+    changePercent: number;
+  };
+}
+
+/**
+ * Summary of diff comparison across all requests.
+ */
+export interface DiffSummary {
+  totalRequests: number;
+  unchanged: number;
+  changed: number;
+  newBaselines: number;
+  results: DiffCompareResult[];
+}

package/src/utils/curl-builder.ts

@@ -133,7 +133,15 @@ export class CurlBuilder {
     status?: number;
     headers?: Record<string, string>;
     body?: string;
-    metrics?: CurlMetrics;
+    metrics?: {
+      duration: number;
+      size?: number;
+      dnsLookup?: number;
+      tcpConnection?: number;
+      tlsHandshake?: number;
+      firstByte?: number;
+      download?: number;
+    };
     error?: string;
   }> {
     try {

package/src/utils/installation-detector.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test';
+import { getUpgradeCommand, getUpgradeCommandWindows, isWindows } from './installation-detector';
+
+describe('getUpgradeCommand', () => {
+  test('returns bun command for bun source', () => {
+    expect(getUpgradeCommand('bun')).toBe('bun install -g @curl-runner/cli@latest');
+  });
+
+  test('returns npm command for npm source', () => {
+    expect(getUpgradeCommand('npm')).toBe('npm install -g @curl-runner/cli@latest');
+  });
+
+  test('returns curl command for curl source', () => {
+    expect(getUpgradeCommand('curl')).toBe(
+      'curl -fsSL https://www.curl-runner.com/install.sh | bash',
+    );
+  });
+
+  test('returns curl command for standalone source', () => {
+    expect(getUpgradeCommand('standalone')).toBe(
+      'curl -fsSL https://www.curl-runner.com/install.sh | bash',
+    );
+  });
+});
+
+describe('getUpgradeCommandWindows', () => {
+  test('returns bun command for bun source', () => {
+    expect(getUpgradeCommandWindows('bun')).toBe('bun install -g @curl-runner/cli@latest');
+  });
+
+  test('returns npm command for npm source', () => {
+    expect(getUpgradeCommandWindows('npm')).toBe('npm install -g @curl-runner/cli@latest');
+  });
+
+  test('returns PowerShell command for curl source', () => {
+    expect(getUpgradeCommandWindows('curl')).toBe(
+      'irm https://www.curl-runner.com/install.ps1 | iex',
+    );
+  });
+
+  test('returns PowerShell command for standalone source', () => {
+    expect(getUpgradeCommandWindows('standalone')).toBe(
+      'irm https://www.curl-runner.com/install.ps1 | iex',
+    );
+  });
+});
+
+describe('isWindows', () => {
+  test('returns boolean based on platform', () => {
+    expect(typeof isWindows()).toBe('boolean');
+  });
+});