@kirrosh/zond 0.21.0 → 0.22.0

package/src/core/reporter/console.ts

@@ -8,11 +8,25 @@ const DIM = "\x1b[2m";
 const GREEN = "\x1b[32m";
 const RED = "\x1b[31m";
 const GRAY = "\x1b[90m";
+const YELLOW = "\x1b[33m";
 
 const PASS_ICON = "\u2713"; // ✓
 const FAIL_ICON = "\u2717"; // ✗
 const SKIP_ICON = "\u25CB"; // ○
 
+export function is5xx(step: StepResult): boolean {
+  const status = step.response?.status;
+  return typeof status === "number" && status >= 500 && status < 600;
+}
+
+export function count5xx(steps: StepResult[]): number {
+  let n = 0;
+  for (const s of steps) {
+    if ((s.status === "fail" || s.status === "error") && is5xx(s)) n++;
+  }
+  return n;
+}
+
 export function formatDuration(ms: number): string {
   if (ms < 1000) return `${Math.round(ms)}ms`;
   if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
@@ -33,11 +47,13 @@ export function formatStep(step: StepResult, color: boolean): string {
     case "fail": {
       const icon = color ? `${RED}${FAIL_ICON}${RESET}` : FAIL_ICON;
       const dim = color ? `${DIM}(${duration})${RESET}` : `(${duration})`;
-      return `  ${icon} ${step.name} ${dim}`;
+      const tag = is5xx(step) ? (color ? ` ${BOLD}${YELLOW}[5xx ${step.response?.status}]${RESET}` : ` [5xx ${step.response?.status}]`) : "";
+      return `  ${icon} ${step.name}${tag} ${dim}`;
     }
     case "skip": {
       const icon = color ? `${GRAY}${SKIP_ICON}${RESET}` : SKIP_ICON;
-      const label = color ? `${GRAY}(skipped)${RESET}` : "(skipped)";
+      const reason = step.error ? `skipped: ${step.error}` : "skipped";
+      const label = color ? `${GRAY}(${reason})${RESET}` : `(${reason})`;
       return `  ${icon} ${step.name} ${label}`;
     }
     case "error": {
@@ -105,6 +121,11 @@ export function formatSuiteResult(result: TestRunResult, color: boolean): string
   if (result.failed > 0) {
     parts.push(color ? `${RED}${result.failed} failed${RESET}` : `${result.failed} failed`);
   }
+  const fiveXx = count5xx(result.steps);
+  if (fiveXx > 0) {
+    const label = `${fiveXx} 5xx`;
+    parts.push(color ? `${BOLD}${YELLOW}${label}${RESET}` : label);
+  }
   if (result.skipped > 0) {
     parts.push(color ? `${GRAY}${result.skipped} skipped${RESET}` : `${result.skipped} skipped`);
   }
@@ -119,7 +140,7 @@ export function formatSuiteResult(result: TestRunResult, color: boolean): string
 }
 
 export function formatGrandTotal(results: TestRunResult[], color: boolean): string {
-  const totals = { passed: 0, failed: 0, skipped: 0, total: 0 };
+  const totals = { passed: 0, failed: 0, skipped: 0, total: 0, fiveXx: 0 };
   let minStart = Infinity;
   let maxEnd = -Infinity;
 
@@ -128,6 +149,7 @@ export function formatGrandTotal(results: TestRunResult[], color: boolean): stri
     totals.failed += r.failed;
     totals.skipped += r.skipped;
     totals.total += r.total;
+    totals.fiveXx += count5xx(r.steps);
     const start = Date.parse(r.started_at);
     const end = Date.parse(r.finished_at);
     if (start < minStart) minStart = start;
@@ -144,6 +166,10 @@ export function formatGrandTotal(results: TestRunResult[], color: boolean): stri
   if (totals.failed > 0) {
     parts.push(color ? `${RED}${totals.failed} failed${RESET}` : `${totals.failed} failed`);
   }
+  if (totals.fiveXx > 0) {
+    const label = `${totals.fiveXx} 5xx`;
+    parts.push(color ? `${BOLD}${YELLOW}${label}${RESET}` : label);
+  }
   if (totals.skipped > 0) {
     parts.push(color ? `${GRAY}${totals.skipped} skipped${RESET}` : `${totals.skipped} skipped`);
   }

package/src/core/reporter/index.ts

@@ -1,7 +1,7 @@
 export type { Reporter, ReporterOptions, ReporterName } from "./types.ts";
 export { consoleReporter, formatDuration, formatStep, formatFailures, formatSuiteResult, formatGrandTotal } from "./console.ts";
-export { jsonReporter } from "./json.ts";
-export { junitReporter } from "./junit.ts";
+export { jsonReporter, generateJsonReport } from "./json.ts";
+export { junitReporter, generateJunitXml } from "./junit.ts";
 
 import type { Reporter, ReporterName } from "./types.ts";
 import { consoleReporter } from "./console.ts";

package/src/core/reporter/json.ts

@@ -1,9 +1,12 @@
 import type { TestRunResult } from "../runner/types.ts";
 import type { Reporter, ReporterOptions } from "./types.ts";
 
+export function generateJsonReport(results: TestRunResult[]): string {
+  return JSON.stringify(results, null, 2);
+}
+
 export const jsonReporter: Reporter = {
   report(results: TestRunResult[], _options?: ReporterOptions): void {
-    const json = JSON.stringify(results, null, 2);
-    console.log(json);
+    console.log(generateJsonReport(results));
   },
 };

package/src/core/runner/assertions.ts

@@ -10,6 +10,7 @@ function checkType(value: unknown, expectedType: string): boolean {
     case "boolean": return typeof value === "boolean";
     case "array": return Array.isArray(value);
     case "object": return typeof value === "object" && value !== null && !Array.isArray(value);
+    case "null": return value === null;
     default: return false;
   }
 }
@@ -37,7 +38,9 @@ function checkRule(path: string, rule: AssertionRule, actual: unknown): Assertio
   const field = `body.${path}`;
 
   if (rule.exists !== undefined) {
-    const doesExist = actual !== undefined && actual !== null;
+    // Key-presence semantics: null counts as "exists" (key present in response).
+    // Use `not_equals: null` or `type: "null"` to assert non-null specifically.
+    const doesExist = actual !== undefined;
     results.push({
       field, rule: `exists ${rule.exists}`,
       passed: doesExist === rule.exists, actual: doesExist, expected: rule.exists,

package/src/core/runner/executor.ts

@@ -3,6 +3,7 @@ import type { TestSuite, TestStep, Environment } from "../parser/types.ts";
 import { substituteString, substituteStep, substituteDeep, extractVariableReferences } from "../parser/variables.ts";
 import type { TestRunResult, StepResult, HttpRequest } from "./types.ts";
 import { executeRequest, type FetchOptions } from "./http-client.ts";
+import type { RateLimiter } from "./rate-limiter.ts";
 import { checkAssertions, extractCaptures } from "./assertions.ts";
 import { evaluateExpr } from "./expr-eval.ts";
 import { applyTransform } from "./transforms.ts";
@@ -28,19 +29,77 @@ function makeSkippedResult(stepName: string, reason: string): StepResult {
   };
 }
 
-export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun = false): Promise<TestRunResult> {
+/** Interpolate {{var}} placeholders inside a test/step name. Falls back to
+ *  the raw name string if substitution returns a non-string value. */
+function interpolateName(name: string, vars: Record<string, unknown>): string {
+  try {
+    const out = substituteString(name, vars);
+    return typeof out === "string" ? out : String(out);
+  } catch {
+    return name;
+  }
+}
+
+/**
+ * Expand a `parameterize: { key: [val, ...] }` map into the cross-product of
+ * iteration variable bindings. No `parameterize` (or an empty map) yields a
+ * single empty iteration so the existing single-pass behaviour is preserved.
+ *
+ * Exported for tests.
+ */
+export function expandParameterize(params?: Record<string, unknown[]>): Record<string, unknown>[] {
+  if (!params) return [{}];
+  const keys = Object.keys(params).filter(k => Array.isArray(params[k]) && (params[k] as unknown[]).length > 0);
+  if (keys.length === 0) return [{}];
+  let combos: Record<string, unknown>[] = [{}];
+  for (const k of keys) {
+    const values = params[k] as unknown[];
+    const next: Record<string, unknown>[] = [];
+    for (const combo of combos) {
+      for (const v of values) {
+        next.push({ ...combo, [k]: v });
+      }
+    }
+    combos = next;
+  }
+  return combos;
+}
+
+export interface RunSuiteOptions {
+  rateLimiter?: RateLimiter;
+}
+
+export async function runSuite(
+  suite: TestSuite,
+  env: Environment = {},
+  dryRun = false,
+  options: RunSuiteOptions = {},
+): Promise<TestRunResult> {
   const startedAt = new Date().toISOString();
   const steps: StepResult[] = [];
-  const variables: Record<string, unknown> = { ...env };
-  const failedCaptures = new Set<string>();
 
   const fetchOptions: Partial<FetchOptions> = {
     timeout: suite.config.timeout,
     retries: suite.config.retries,
     retry_delay: suite.config.retry_delay,
     follow_redirects: suite.config.follow_redirects,
+    rate_limiter: options.rateLimiter,
   };
 
+  // parameterize cross-product → N iterations of the suite body.
+  // Captures and tainted/missing sets are reset per iteration so that
+  // values from one binding never leak into the next.
+  const iterations = expandParameterize(suite.parameterize);
+
+  for (const iterVars of iterations) {
+  const variables: Record<string, unknown> = { ...env, ...iterVars };
+  // Captures whose source step's assertions partially failed, but the value
+  // itself was extracted. Cleanup/always steps may still consume them.
+  const taintedCaptures = new Set<string>();
+  // Captures that were never extracted (response missing the field). Even
+  // always-steps can't run if their referenced capture is missing.
+  const missingCaptures = new Set<string>();
+
   // Expand steps lazily (for_each needs current variables)
   let stepIndex = 0;
   const rawSteps = [...suite.tests];
@@ -86,7 +145,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
         variables[key] = applyTransform(substituted);
       }
       steps.push({
-        name: step.name,
+        name: interpolateName(step.name, variables),
         status: "pass",
         duration_ms: 0,
         request: { method: "", url: "", headers: {} },
@@ -96,37 +155,65 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       continue;
     }
 
-    // Skip check: if step references a failed capture variable, skip it
+    // Skip check: if step references a failed capture, skip — unless
+    // step is `always: true` AND the capture is just tainted (still extracted).
     const referencedVars = extractVariableReferences(step);
-    const missingCapture = referencedVars.find((v) => failedCaptures.has(v));
-    if (missingCapture) {
-      steps.push(makeSkippedResult(step.name, `Depends on missing capture: ${missingCapture}`));
+    const missing = referencedVars.find((v) => missingCaptures.has(v));
+    if (missing) {
+      steps.push(makeSkippedResult(interpolateName(step.name, variables), `Depends on missing capture: ${missing}`));
       continue;
     }
+    if (!step.always) {
+      const tainted = referencedVars.find((v) => taintedCaptures.has(v));
+      if (tainted) {
+        steps.push(makeSkippedResult(interpolateName(step.name, variables), `Depends on tainted capture: ${tainted} (use always: true on cleanup steps)`));
+        continue;
+      }
+    }
 
     // skip_if evaluation
     if (step.skip_if) {
       const exprAfterSubst = String(substituteString(step.skip_if, variables));
       if (evaluateExpr(exprAfterSubst)) {
-        steps.push(makeSkippedResult(step.name, `Skipped: ${step.skip_if}`));
+        steps.push(makeSkippedResult(interpolateName(step.name, variables), `Skipped: ${step.skip_if}`));
         continue;
       }
     }
 
-    // Process set: on HTTP steps — evaluate generators once before building request
-    if (step.set) {
-      for (const [key, rawDirective] of Object.entries(step.set)) {
-        const substituted = substituteDeep(rawDirective, variables);
-        variables[key] = applyTransform(substituted);
+    // Process set: on HTTP steps — evaluate generators once before building request.
+    // Substitution can throw on unknown {{$generator}} — fail this step, not the suite.
+    let resolved: TestStep;
+    let resolvedBaseUrl: string | undefined;
+    let resolvedSuiteHeaders: Record<string, string> | undefined;
+    try {
+      if (step.set) {
+        for (const [key, rawDirective] of Object.entries(step.set)) {
+          const substituted = substituteDeep(rawDirective, variables);
+          variables[key] = applyTransform(substituted);
+        }
+      }
+      resolved = substituteStep(step, variables);
+      resolvedBaseUrl = suite.base_url ? substituteString(suite.base_url, variables) as string : undefined;
+      resolvedSuiteHeaders = suite.headers ? substituteDeep(suite.headers, variables) : undefined;
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      steps.push({
+        name: interpolateName(step.name, variables),
+        status: "error",
+        duration_ms: 0,
+        request: { method: step.method, url: step.path, headers: {} },
+        assertions: [],
+        captures: {},
+        error: errorMsg,
+      });
+      // Substitution never produced a request → capture truly missing.
+      if (step.expect.body) {
+        for (const rule of Object.values(step.expect.body)) {
+          if (rule.capture) missingCaptures.add(rule.capture);
+        }
       }
+      continue;
     }
-
-    // Substitute variables
-    const resolved = substituteStep(step, variables);
-
-    // Build request — substitute base_url and suite headers with current variables
-    const resolvedBaseUrl = suite.base_url ? substituteString(suite.base_url, variables) as string : undefined;
-    const resolvedSuiteHeaders = suite.headers ? substituteDeep(suite.headers, variables) : undefined;
     const url = buildUrl(resolvedBaseUrl, resolved.path, resolved.query);
     const headers: Record<string, string> = { ...resolvedSuiteHeaders, ...resolved.headers };
     let body: string | undefined;
@@ -163,7 +250,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
     // Validate absolute URL before attempting fetch
     if (!url.startsWith("http://") && !url.startsWith("https://")) {
       steps.push({
-        name: step.name,
+        name: interpolateName(step.name, variables),
         status: "error",
         duration_ms: 0,
         request,
@@ -173,7 +260,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       });
       if (step.expect.body) {
         for (const rule of Object.values(step.expect.body)) {
-          if (rule.capture) failedCaptures.add(rule.capture);
+          if (rule.capture) missingCaptures.add(rule.capture);
         }
       }
       continue;
@@ -184,7 +271,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
         ? ` [multipart: ${[...formData.keys()].length} field(s)]`
         : body ? ` ${body.slice(0, 200)}` : "";
       steps.push({
-        name: step.name,
+        name: interpolateName(step.name, variables),
         status: "pass",
         duration_ms: 0,
         request,
@@ -207,7 +294,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
           const allPassed = assertions.every((a) => a.passed);
 
           lastStepResult = {
-            name: step.name,
+            name: interpolateName(step.name, variables),
             status: allPassed ? "pass" : "fail",
             duration_ms: response.duration_ms,
             request,
@@ -234,7 +321,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
           }
         } catch (err) {
           lastStepResult = {
-            name: step.name,
+            name: interpolateName(step.name, variables),
             status: "error",
             duration_ms: 0,
             request,
@@ -255,11 +342,11 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       const captures = extractCaptures(resolved.expect.body, response.body_parsed, resolved.expect.headers, response.headers);
       Object.assign(variables, captures);
 
-      // Track expected captures that weren't obtained
+      // Track expected captures that weren't obtained — these are missing.
       if (resolved.expect.body) {
         for (const rule of Object.values(resolved.expect.body)) {
           if (rule.capture && !(rule.capture in captures)) {
-            failedCaptures.add(rule.capture);
+            missingCaptures.add(rule.capture);
           }
         }
       }
@@ -269,7 +356,7 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
       const allPassed = assertions.every((a) => a.passed);
 
       steps.push({
-        name: step.name,
+        name: interpolateName(step.name, variables),
         status: allPassed ? "pass" : "fail",
         duration_ms: response.duration_ms,
         request,
@@ -278,18 +365,20 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
         captures,
       });
 
-      // If step failed, mark its captures as unreliable
+      // If step failed, captures that did extract are tainted (value is real
+      // but came from a step whose other assertions failed). Always-steps may
+      // still consume them; non-always steps cascade-skip.
       if (!allPassed && resolved.expect.body) {
         for (const rule of Object.values(resolved.expect.body)) {
-          if (rule.capture) {
-            failedCaptures.add(rule.capture);
+          if (rule.capture && rule.capture in captures) {
+            taintedCaptures.add(rule.capture);
           }
         }
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
       steps.push({
-        name: step.name,
+        name: interpolateName(step.name, variables),
         status: "error",
         duration_ms: 0,
         request,
@@ -298,14 +387,15 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
         error: errorMsg,
       });
 
-      // Mark any captures from this step as failed
+      // Network/runtime error → no response → capture truly missing.
       if (step.expect.body) {
         for (const rule of Object.values(step.expect.body)) {
-          if (rule.capture) failedCaptures.add(rule.capture);
+          if (rule.capture) missingCaptures.add(rule.capture);
         }
       }
     }
   }
+  } // end of parameterize iteration loop
 
   const finishedAt = new Date().toISOString();
   return {
@@ -323,6 +413,11 @@ export async function runSuite(suite: TestSuite, env: Environment = {}, dryRun =
   };
 }
 
-export async function runSuites(suites: TestSuite[], env: Environment = {}, dryRun = false): Promise<TestRunResult[]> {
-  return Promise.all(suites.map((suite) => runSuite(suite, env, dryRun)));
+export async function runSuites(
+  suites: TestSuite[],
+  env: Environment = {},
+  dryRun = false,
+  options: RunSuiteOptions = {},
+): Promise<TestRunResult[]> {
+  return Promise.all(suites.map((suite) => runSuite(suite, env, dryRun, options)));
 }

package/src/core/runner/http-client.ts

@@ -1,10 +1,14 @@
 import type { HttpRequest, HttpResponse } from "./types.ts";
+import { type RateLimiter, parseRetryAfter, parseRateLimitHeaders } from "./rate-limiter.ts";
 
 export interface FetchOptions {
   timeout: number;
   retries: number;
   retry_delay: number;
   follow_redirects: boolean;
+  rate_limiter?: RateLimiter;
+  rate_limit_retries: number;
+  rate_limit_max_delay_ms: number;
 }
 
 export const DEFAULT_FETCH_OPTIONS: FetchOptions = {
@@ -12,6 +16,8 @@ export const DEFAULT_FETCH_OPTIONS: FetchOptions = {
   retries: 0,
   retry_delay: 1000,
   follow_redirects: true,
+  rate_limit_retries: 5,
+  rate_limit_max_delay_ms: 30000,
 };
 
 export async function executeRequest(
@@ -20,10 +26,12 @@ export async function executeRequest(
 ): Promise<HttpResponse> {
   const opts = { ...DEFAULT_FETCH_OPTIONS, ...options };
   let lastError: Error | undefined;
+  let networkAttempt = 0;
+  let rate429Attempt = 0;
 
-  for (let attempt = 0; attempt <= opts.retries; attempt++) {
-    if (attempt > 0) {
-      await Bun.sleep(opts.retry_delay);
+  while (true) {
+    if (opts.rate_limiter) {
+      await opts.rate_limiter.acquire();
     }
 
     try {
@@ -43,6 +51,20 @@ export async function executeRequest(
       clearTimeout(timeoutId);
       const duration_ms = Math.round(performance.now() - start);
 
+      if (response.status === 429 && rate429Attempt < opts.rate_limit_retries) {
+        const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+        const backoffMs = Math.min(
+          opts.retry_delay * 2 ** rate429Attempt,
+          opts.rate_limit_max_delay_ms,
+        );
+        const waitMs = Math.min(retryAfterMs ?? backoffMs, opts.rate_limit_max_delay_ms);
+        rate429Attempt++;
+        // Drain body so the connection can be reused
+        await response.text().catch(() => undefined);
+        await Bun.sleep(waitMs);
+        continue;
+      }
+
       const bodyText = await response.text();
       let body_parsed: unknown = undefined;
       const contentType = response.headers.get("content-type") ?? "";
@@ -69,11 +91,24 @@ export async function executeRequest(
         headers[k] = v;
       });
 
+      // Feed ratelimit-* headers back into the limiter so it can pause the
+      // stream proactively when the window is nearly exhausted (TASK-81).
+      if (opts.rate_limiter?.note) {
+        const meta = parseRateLimitHeaders(headers);
+        if (meta.remaining !== undefined || meta.reset !== undefined) {
+          opts.rate_limiter.note(meta);
+        }
+      }
+
       return { status: response.status, headers, body: bodyText, body_parsed, duration_ms };
     } catch (err) {
       lastError = err instanceof Error ? err : new Error(String(err));
+      if (networkAttempt < opts.retries) {
+        networkAttempt++;
+        await Bun.sleep(opts.retry_delay);
+        continue;
+      }
+      throw lastError;
     }
   }
-
-  throw lastError!;
 }

package/src/core/runner/rate-limiter.ts

@@ -0,0 +1,131 @@
+export interface RateLimiter {
+  acquire(): Promise<void>;
+  /**
+   * Feed rate-limit metadata from the latest response back into the limiter.
+   * When `remaining` falls at or below the threshold, the limiter postpones
+   * the next acquire until the API's reset window expires. No-op when the
+   * server reports plenty of headroom.
+   *
+   * Optional so existing callers / mocks need not implement it.
+   */
+  note?(meta: RateLimitMeta, now?: number): void;
+}
+
+export interface RateLimitMeta {
+  /** Requests remaining in the current window. */
+  remaining?: number;
+  /** Either seconds-until-reset (RFC draft) or a Unix epoch in seconds (GitHub style). */
+  reset?: number;
+  /** Window cap; used only for diagnostics. */
+  limit?: number;
+}
+
+/** When `remaining` is at or below this number we proactively pause until reset. */
+const THROTTLE_THRESHOLD = 5;
+
+/** Magnitudes above this are treated as Unix timestamps; below as relative
+ *  seconds. 10^9 seconds ≈ Sep 2001, so any real reset window is far below. */
+const UNIX_TS_BOUNDARY = 1_000_000_000;
+
+function applyMeta(prevNextAvailable: number, meta: RateLimitMeta, now: number): number {
+  if (meta.remaining === undefined) return prevNextAvailable;
+  if (meta.remaining > THROTTLE_THRESHOLD) return prevNextAvailable;
+  if (meta.reset === undefined || !Number.isFinite(meta.reset)) return prevNextAvailable;
+  const resetMs = meta.reset > UNIX_TS_BOUNDARY ? meta.reset * 1000 : now + Math.max(0, meta.reset) * 1000;
+  return Math.max(prevNextAvailable, resetMs);
+}
+
+class IntervalRateLimiter implements RateLimiter {
+  private nextAvailable = 0;
+  private readonly intervalMs: number;
+
+  constructor(reqPerSec: number) {
+    if (!Number.isFinite(reqPerSec) || reqPerSec <= 0) {
+      throw new Error(`Invalid rate limit: ${reqPerSec}`);
+    }
+    this.intervalMs = 1000 / reqPerSec;
+  }
+
+  async acquire(): Promise<void> {
+    const now = Date.now();
+    const slot = Math.max(now, this.nextAvailable);
+    const waitMs = slot - now;
+    this.nextAvailable = slot + this.intervalMs;
+    if (waitMs > 0) {
+      await Bun.sleep(waitMs);
+    }
+  }
+
+  note(meta: RateLimitMeta, now: number = Date.now()): void {
+    this.nextAvailable = applyMeta(this.nextAvailable, meta, now);
+  }
+}
+
+class AdaptiveRateLimiter implements RateLimiter {
+  private nextAvailable = 0;
+
+  async acquire(): Promise<void> {
+    const now = Date.now();
+    const wait = this.nextAvailable - now;
+    if (wait > 0) await Bun.sleep(wait);
+  }
+
+  note(meta: RateLimitMeta, now: number = Date.now()): void {
+    this.nextAvailable = applyMeta(this.nextAvailable, meta, now);
+  }
+}
+
+export function createRateLimiter(reqPerSec: number | undefined): RateLimiter | undefined {
+  if (reqPerSec === undefined || reqPerSec === null) return undefined;
+  if (!Number.isFinite(reqPerSec) || reqPerSec <= 0) return undefined;
+  return new IntervalRateLimiter(reqPerSec);
+}
+
+/**
+ * Adaptive limiter for `--rate-limit auto`. Issues no proactive throttling on
+ * its own, but reacts to ratelimit-* response headers via `note()` and pauses
+ * the request stream until the API's reset window elapses when headroom drops.
+ */
+export function createAdaptiveRateLimiter(): RateLimiter {
+  return new AdaptiveRateLimiter();
+}
+
+/**
+ * Read RFC draft-ietf-httpapi-ratelimit-headers (`ratelimit-*`) plus the
+ * GitHub / Stripe style `x-ratelimit-*` aliases out of a response header bag.
+ * All keys are matched case-insensitively. Unparseable values are dropped.
+ */
+export function parseRateLimitHeaders(headers: Record<string, string>): RateLimitMeta {
+  const lower: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
+  const num = (v: string | undefined): number | undefined => {
+    if (v === undefined) return undefined;
+    // RFC draft `ratelimit-remaining` may carry `q="value"` quoted-string form;
+    // strip leading numeric run.
+    const match = v.match(/-?\d+(?:\.\d+)?/);
+    if (!match) return undefined;
+    const n = Number.parseFloat(match[0]);
+    return Number.isFinite(n) ? n : undefined;
+  };
+  return {
+    limit: num(lower["ratelimit-limit"] ?? lower["x-ratelimit-limit"]),
+    remaining: num(lower["ratelimit-remaining"] ?? lower["x-ratelimit-remaining"]),
+    reset: num(lower["ratelimit-reset"] ?? lower["x-ratelimit-reset"]),
+  };
+}
+
+export function parseRetryAfter(header: string | null | undefined, now: number = Date.now()): number | undefined {
+  if (!header) return undefined;
+  const trimmed = header.trim();
+  if (trimmed === "") return undefined;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const seconds = Number.parseFloat(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1000);
+    return undefined;
+  }
+  const date = Date.parse(trimmed);
+  if (!Number.isNaN(date)) {
+    return Math.max(0, date - now);
+  }
+  return undefined;
+}

package/src/core/setup-api.ts

@@ -3,6 +3,7 @@ import { mkdirSync, writeFileSync, existsSync, readFileSync } from "fs";
 import { getDb } from "../db/schema.ts";
 import { createCollection, deleteCollection, findCollectionByNameOrId, normalizePath } from "../db/queries.ts";
 import { readOpenApiSpec, extractEndpoints } from "./generator/index.ts";
+import { findWorkspaceRoot } from "./workspace/root.ts";
 
 function toYaml(vars: Record<string, string>): string {
   const lines: string[] = [];
@@ -90,7 +91,9 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
 
   // Sanitize name for directory use
   const dirName = name.replace(/[^a-zA-Z0-9_\-\.]/g, "-").toLowerCase();
-  const baseDir = resolve(options.dir ?? `./apis/${dirName}/`);
+  const baseDir = options.dir
+    ? resolve(options.dir)
+    : resolve(findWorkspaceRoot().root, `apis/${dirName}/`);
   const testPath = join(baseDir, "tests");
 
   // Create directories