@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/runner/send-request.ts

@@ -2,23 +2,61 @@ import { executeRequest } from "./http-client.ts";
 import { loadEnvironment, substituteString, substituteDeep } from "../parser/variables.ts";
 import { getDb } from "../../db/schema.ts";
 import { findCollectionByNameOrId } from "../../db/queries.ts";
+import { encodeFormBody } from "./form-encode.ts";
 
-function extractByPath(obj: unknown, path: string): unknown {
-  const segments = path.replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+function hasHeaderCI(headers: Record<string, string>, name: string): boolean {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}
+
+export function extractByPath(obj: unknown, path: string): unknown {
+  return extractByPathWithDiagnostic(obj, path).value;
+}
+
+/** ARV-70 (feedback round-01 / F11): same extractor as above but also
+ *  reports *why* the path failed. The CLI surfaces this on stderr when
+ *  `--json-path` returns undefined so users don't lose minutes debugging
+ *  "empty stdout despite data[0].id is right there in the JSON" — the
+ *  hint pinpoints the segment that didn't resolve (e.g. "body is a string
+ *  — content-type was not application/json"). */
+export function extractByPathWithDiagnostic(
+  obj: unknown,
+  path: string,
+): { value: unknown; resolved: string[]; failedAt?: string; reason?: string } {
+  const segments = path.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+  const resolved: string[] = [];
   let current: unknown = obj;
   for (const seg of segments) {
-    if (current === null || current === undefined) return undefined;
+    if (current === null || current === undefined) {
+      return { value: undefined, resolved, failedAt: seg, reason: "previous segment resolved to null/undefined" };
+    }
     if (Array.isArray(current)) {
       const idx = parseInt(seg, 10);
-      if (isNaN(idx)) return undefined;
+      if (isNaN(idx)) {
+        return { value: undefined, resolved, failedAt: seg, reason: `expected an array index, got non-numeric segment "${seg}"` };
+      }
+      if (idx < 0 || idx >= current.length) {
+        return { value: undefined, resolved, failedAt: seg, reason: `array index ${idx} out of bounds (length ${current.length})` };
+      }
       current = current[idx];
-    } else if (typeof current === 'object') {
-      current = (current as Record<string, unknown>)[seg];
+    } else if (typeof current === "object") {
+      const obj = current as Record<string, unknown>;
+      if (!(seg in obj)) {
+        const keys = Object.keys(obj).slice(0, 8).join(", ");
+        return { value: undefined, resolved, failedAt: seg, reason: `key "${seg}" not in object (keys: ${keys || "<empty>"})` };
+      }
+      current = obj[seg];
     } else {
-      return undefined;
+      return {
+        value: undefined,
+        resolved,
+        failedAt: seg,
+        reason: `cannot traverse "${seg}" — body is a ${typeof current === "string" ? "string (content-type may not be application/json)" : typeof current}`,
+      };
     }
+    resolved.push(seg);
   }
-  return current;
+  return { value: current, resolved };
 }
 
 export interface SendAdHocRequestOptions {
@@ -33,6 +71,15 @@ export interface SendAdHocRequestOptions {
   maxResponseChars?: number;
   dbPath?: string;
   searchDir?: string;
+  /** Extra vars merged on top of env (e.g. captured values from a stored run). */
+  extraVars?: Record<string, unknown>;
+  /** When true, resolve interpolation but do not actually send the request. */
+  dryRun?: boolean;
+  /** ARV-149: when true, send the body as `application/x-www-form-urlencoded`.
+   *  Parses `body` as JSON to lift fields, then re-encodes with bracket notation
+   *  (Stripe-style nested keys). If `body` isn't JSON-parseable it's passed
+   *  through verbatim, and only the Content-Type header is set. */
+  form?: boolean;
 }
 
 export interface SendAdHocRequestResult {
@@ -40,25 +87,75 @@ export interface SendAdHocRequestResult {
   headers: Record<string, string>;
   body: unknown;
   duration_ms: number;
+  /** ARV-70: when --json-path failed to resolve, this carries which
+   *  segment broke and why so the CLI can surface a hint on stderr. */
+  jsonPathDiagnostic?: { resolved: string[]; failedAt?: string; reason?: string };
 }
 
-export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promise<SendAdHocRequestResult> {
+export interface ResolvedRequest {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+export async function resolveAdHocRequest(options: SendAdHocRequestOptions): Promise<ResolvedRequest> {
   let searchDir = options.searchDir ?? process.cwd();
   if (options.collectionName) {
     getDb(options.dbPath);
     const col = findCollectionByNameOrId(options.collectionName);
-    if (col?.base_dir) searchDir = col.base_dir;
+    if (!col) {
+      throw new Error(`API '${options.collectionName}' is not registered. Run \`zond add api <name> --base-url <url>\` first, or check the name with \`zond db collections\`.`);
+    }
+    if (col.base_dir) searchDir = col.base_dir;
+  }
+  const envVars = await loadEnvironment(options.envName, searchDir);
+  const vars = options.extraVars ? { ...envVars, ...options.extraVars } : envVars;
+
+  // Auto-prefix base_url for relative paths when --api is in play.
+  // Mirror the YAML-runner ergonomics: `zond request --api jp GET /users/1`
+  // should work the same as `... GET '{{base_url}}/users/1'`. We touch the URL
+  // only when it's clearly relative (leading "/") and has no scheme/template
+  // already, so absolute URLs and explicit {{var}} templates pass through.
+  let urlToResolve = options.url;
+  if (
+    options.collectionName
+    && typeof vars.base_url === "string"
+    && vars.base_url.length > 0
+    && urlToResolve.startsWith("/")
+    && !urlToResolve.startsWith("//")
+  ) {
+    const base = vars.base_url.replace(/\/+$/, "");
+    urlToResolve = `${base}${urlToResolve}`;
   }
-  const vars = await loadEnvironment(options.envName, searchDir);
 
-  const resolvedUrl = substituteString(options.url, vars) as string;
+  const resolvedUrl = substituteString(urlToResolve, vars) as string;
   const parsedHeaders = options.headers ?? {};
   const resolvedHeaders = Object.keys(parsedHeaders).length > 0 ? substituteDeep(parsedHeaders, vars) : {};
-  const resolvedBody = options.body ? substituteString(options.body, vars) as string : undefined;
+  let resolvedBody = options.body ? substituteString(options.body, vars) as string : undefined;
 
-  // Auto-detect Content-Type for body if not explicitly set
   const finalHeaders: Record<string, string> = { ...resolvedHeaders };
-  if (resolvedBody && !finalHeaders["Content-Type"] && !finalHeaders["content-type"]) {
+  const hasContentType =
+    finalHeaders["Content-Type"] !== undefined || finalHeaders["content-type"] !== undefined;
+
+  // ARV-149: `--form` (or auto-detection from spec content type) re-encodes
+  // the JSON body as `application/x-www-form-urlencoded` with bracket
+  // notation. Stripe v1 and other Rails/PHP-style APIs declare ONLY form
+  // bodies on their mutating endpoints — sending JSON yields a 400
+  // "check that your POST content type is application/x-www-form-urlencoded".
+  if (resolvedBody && options.form) {
+    try {
+      const parsed = JSON.parse(resolvedBody);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        resolvedBody = encodeFormBody(parsed as Record<string, unknown>);
+      }
+    } catch {
+      // Body isn't JSON — assume it's already urlencoded; pass through verbatim.
+    }
+    if (!hasContentType) {
+      finalHeaders["Content-Type"] = "application/x-www-form-urlencoded";
+    }
+  } else if (resolvedBody && !hasContentType) {
     try {
       JSON.parse(resolvedBody);
       finalHeaders["Content-Type"] = "application/json";
@@ -67,20 +164,55 @@ export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promis
     }
   }
 
+  // TASK-231: when --api resolved an env with `auth_token`, auto-inject the
+  // standard `Authorization: Bearer …` header. This mirrors the YAML runner's
+  // behaviour (probes/suites template the same header from the security
+  // scheme) so `zond request --api X GET /…` doesn't 401 just because the
+  // user didn't repeat `--header "Authorization: Bearer {{auth_token}}"`.
+  // User-supplied Authorization always wins.
+  if (
+    options.collectionName
+    && typeof vars.auth_token === "string"
+    && vars.auth_token.length > 0
+    && !hasHeaderCI(finalHeaders, "Authorization")
+  ) {
+    finalHeaders["Authorization"] = `Bearer ${vars.auth_token}`;
+  }
+
+  return {
+    method: options.method,
+    url: resolvedUrl,
+    headers: finalHeaders,
+    ...(resolvedBody !== undefined ? { body: resolvedBody } : {}),
+  };
+}
+
+// Note: `options.form` is consumed inside `resolveAdHocRequest` itself —
+// the encoded `body` string and Content-Type are baked into `finalHeaders`.
+// `sendAdHocRequest` doesn't need to forward the flag separately.
+
+export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promise<SendAdHocRequestResult> {
+  const resolved = await resolveAdHocRequest(options);
+
   const response = await executeRequest(
     {
-      method: options.method,
-      url: resolvedUrl,
-      headers: finalHeaders,
-      body: resolvedBody,
+      method: resolved.method,
+      url: resolved.url,
+      headers: resolved.headers,
+      body: resolved.body,
     },
     options.timeout ? { timeout: options.timeout } : undefined,
   );
 
   let responseBody: unknown = response.body_parsed ?? response.body;
+  let jsonPathDiagnostic: SendAdHocRequestResult["jsonPathDiagnostic"];
 
   if (options.jsonPath && responseBody !== undefined) {
-    responseBody = extractByPath(responseBody, options.jsonPath);
+    const diag = extractByPathWithDiagnostic(responseBody, options.jsonPath);
+    responseBody = diag.value;
+    if (diag.value === undefined && diag.failedAt) {
+      jsonPathDiagnostic = { resolved: diag.resolved, failedAt: diag.failedAt, reason: diag.reason };
+    }
   }
 
   const result: SendAdHocRequestResult = {
@@ -88,6 +220,7 @@ export async function sendAdHocRequest(options: SendAdHocRequestOptions): Promis
     headers: response.headers,
     body: responseBody,
     duration_ms: response.duration_ms,
+    ...(jsonPathDiagnostic ? { jsonPathDiagnostic } : {}),
   };
 
   return result;

package/src/core/runner/types.ts

@@ -14,14 +14,26 @@ export interface HttpResponse {
   body: string;
   body_parsed?: unknown;
   duration_ms: number;
+  /** TASK-144: number of network-level retries that preceded this response.
+   *  0 when the request succeeded on the first attempt. */
+  network_retry_count?: number;
 }
 
+/**
+ * `kind` lets the UI surface the assertion that matches the test's stated
+ * intent (primary) ahead of OpenAPI schema noise (schema) and housekeeping
+ * checks like duration/header asserts (auxiliary). Optional for backwards
+ * compatibility — older runs render as `primary` by default.
+ */
+export type AssertionKind = "primary" | "schema" | "auxiliary";
+
 export interface AssertionResult {
   field: string;
   rule: string;
   passed: boolean;
   actual: unknown;
   expected: unknown;
+  kind?: AssertionKind;
 }
 
 export interface StepResult {
@@ -33,6 +45,32 @@ export interface StepResult {
   assertions: AssertionResult[];
   captures: Record<string, unknown>;
   error?: string;
+  provenance?: import("../parser/types.ts").SourceMetadata | null;
+  /** TASK-101: classification of why this failure happened — definitely_bug,
+   *  likely_bug, quirk, env_issue. `null` for passed/skipped/unclassifiable. */
+  failure_class?: import("../diagnostics/failure-class.ts").FailureClass | null;
+  failure_class_reason?: string | null;
+  /** TASK-102: JSON Pointer into the OpenAPI doc + frozen excerpt of the
+   *  schema at that pointer. Captured at run time so later spec edits don't
+   *  rewrite history. `null` for manual YAML or when spec isn't available. */
+  spec_pointer?: string | null;
+  spec_excerpt?: string | null;
+  /** TASK-144: how many network-level retries the http-client performed
+   *  before this step settled. Omitted (or 0) when no retry was needed.
+   *  Surfaced in the JSON report so flaky-network steps are visible. */
+  network_retry?: number;
+  /** ARV-157: summary of `--validate-schema` outcome for this step. Present
+   *  only when the runner had a schema validator attached AND a JSON body
+   *  was returned (so consumers can distinguish "no drift" from "never
+   *  validated"). Granular failures still live in `assertions[]` with
+   *  `kind: "schema"`; this block is the at-a-glance shape skill docs
+   *  describe and JSON-report consumers grep for. */
+  schema_validation?: {
+    result: "PASS" | "FAIL" | "no-endpoint" | "no-schema";
+    matched_endpoint: { method: string; path: string } | null;
+    matched_response_status: string | null;
+    error_count: number;
+  };
 }
 
 export interface TestRunResult {

package/src/core/secrets/registry.ts

@@ -0,0 +1,164 @@
+/**
+ * SecretRegistry — runtime registry of secret values + sanitizer
+ * (TASK-166, m-10).
+ *
+ * The registry is the single point that knows "this string is a secret;
+ * if you see it anywhere in a request URL, body, response, log line, or
+ * exporter, replace it with `<redacted:<var-name>>`". Every persisted
+ * artifact path (DB-write — TASK-167, exporters — TASK-168) calls
+ * `redact()` / `redactObject()` before writing, so the user can ship a
+ * digest / HTML report without scrubbing tokens by hand.
+ *
+ * Design rules:
+ *   - Exact-match only — no heuristics ("looks like a JWT", "starts with
+ *     `sk_`"). False positives are worse than false negatives here.
+ *   - Minimum length 8 — protects against `auth_token: ""` or `id: 1`
+ *     turning every "1" in the report into `<redacted>`.
+ *   - One marker format documented in one place: `<redacted:<name>>`.
+ *   - `setEnabled(false)` returns a no-op redactor for `--no-redact` (local
+ *     debug). Default is enabled.
+ *
+ * Marker format: `<redacted:auth_token>` — the name comes from the
+ * variable that registered the value (e.g. `.env.yaml` key, `--env` flag,
+ * `.secrets.yaml` future entry). Anything that opens a redacted artifact
+ * sees the variable name and knows where to look it up locally.
+ */
+
+/** Minimum length below which a registered value is silently ignored. */
+export const MIN_SECRET_LENGTH = 8;
+
+const REDACTED_MARKER_RE = /<redacted:[a-zA-Z0-9_.-]+>/;
+
+export interface SecretEntry {
+  name: string;
+  value: string;
+}
+
+export class SecretRegistry {
+  /** value → name. We keep map keyed by *value* so a single redact pass
+   *  iterates the unique values rather than all registrations. Two names
+   *  registering the same value collapse to one entry — the most recent
+   *  wins. */
+  private byValue = new Map<string, string>();
+  private enabled = true;
+
+  register(name: string, value: unknown): void {
+    if (typeof value !== "string") return;
+    if (value.length < MIN_SECRET_LENGTH) return;
+    this.byValue.set(value, name);
+  }
+
+  /**
+   * Bulk-register every string value in a flat object. Used by
+   * `.env.yaml` / `.secrets.yaml` loaders so we don't have to know in
+   * advance which keys are sensitive. The variable name carried into the
+   * marker is the object key.
+   */
+  registerAll(entries: Record<string, unknown> | undefined | null): void {
+    if (!entries) return;
+    for (const [k, v] of Object.entries(entries)) this.register(k, v);
+  }
+
+  /** Disable redaction (for `--no-redact` local debug). */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /** Names of every var that had a value registered. Stable diagnostic. */
+  redactedNames(): string[] {
+    return [...new Set(this.byValue.values())].sort();
+  }
+
+  hasSecrets(): boolean {
+    return this.byValue.size > 0;
+  }
+
+  /** Drop all registered secrets — used between test cases. */
+  clear(): void {
+    this.byValue.clear();
+  }
+
+  /**
+   * Replace every occurrence of a registered value in `text` with the
+   * marker `<redacted:<name>>`. Longest values first, so a token that
+   * happens to contain a shorter registered substring still ends up
+   * redacted as the more-specific match.
+   */
+  redact(text: string): string {
+    if (!this.enabled || this.byValue.size === 0) return text;
+    if (typeof text !== "string" || text.length === 0) return text;
+
+    let out = text;
+    for (const [value, name] of this.sortedEntries()) {
+      if (out.indexOf(value) === -1) continue;
+      out = out.split(value).join(`<redacted:${name}>`);
+    }
+    return out;
+  }
+
+  /**
+   * Deep-clone variant for arbitrary structured data (request/response
+   * bodies, header maps, JSON envelopes). Strings get redacted; numbers,
+   * booleans, null, Buffers stay as-is. Cycles are not expected on the
+   * artifact paths but we guard with `seen` to be safe.
+   */
+  redactObject<T>(obj: T): T {
+    if (!this.enabled || this.byValue.size === 0) return obj;
+    return this.deepRedact(obj, new WeakSet()) as T;
+  }
+
+  private sortedEntries(): Array<[string, string]> {
+    return [...this.byValue.entries()].sort((a, b) => b[0].length - a[0].length);
+  }
+
+  private deepRedact(node: unknown, seen: WeakSet<object>): unknown {
+    if (node == null) return node;
+    if (typeof node === "string") return this.redact(node);
+    if (typeof node !== "object") return node;
+    if (seen.has(node as object)) return node;
+    seen.add(node as object);
+
+    if (Array.isArray(node)) {
+      return node.map((v) => this.deepRedact(v, seen));
+    }
+    // Buffers / Uint8Array / Date — leave intact.
+    if (node instanceof Uint8Array || node instanceof Date) return node;
+
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(node)) {
+      out[k] = this.deepRedact(v, seen);
+    }
+    return out;
+  }
+}
+
+/**
+ * Process-wide registry. CLI commands populate it once after loading
+ * `.env.yaml` / `.secrets.yaml`; library callers can pass their own
+ * instance instead of touching this singleton in tests.
+ */
+let globalRegistry: SecretRegistry | undefined;
+
+export function getSecretRegistry(): SecretRegistry {
+  if (!globalRegistry) globalRegistry = new SecretRegistry();
+  return globalRegistry;
+}
+
+/** Replace the global registry. Tests use this to reset state. */
+export function setSecretRegistry(reg: SecretRegistry): void {
+  globalRegistry = reg;
+}
+
+/** Convenience: redact a string via the global registry. */
+export function redact(text: string): string {
+  return getSecretRegistry().redact(text);
+}
+
+/** Convenience: redact a nested object via the global registry. */
+export function redactObject<T>(value: T): T {
+  return getSecretRegistry().redactObject(value);
+}

package/src/core/secrets/secrets-file.ts

@@ -0,0 +1,115 @@
+/**
+ * `.secrets.yaml` — gitignored flat YAML file holding raw secret values
+ * for an API (TASK-170, m-10). Companion to `.env.yaml` which references
+ * keys here via `@secret:<name>`.
+ *
+ *     # apis/<name>/.secrets.yaml (NEVER committed)
+ *     auth_token: "tok_..."
+ *     dsn: "https://...@example.com/..."
+ *
+ *     # apis/<name>/.env.yaml (committable)
+ *     auth_token: "@secret:auth_token"
+ *     base_url: "https://api.example.com"
+ *
+ * Mental model: anything in `.secrets.yaml` is registered with the
+ * `SecretRegistry` at load-time, so it gets redacted in any persisted
+ * artifact (DB, exporters, digests). Anything in `.env.yaml` is plain.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getSecretRegistry } from "./registry.ts";
+
+const SECRETS_FILENAME = ".secrets.yaml";
+const SECRET_REF_RE = /^@secret:([A-Za-z_][A-Za-z0-9_.-]*)$/;
+
+/** Resolved contents of a `.secrets.yaml`. */
+export interface SecretsFile {
+  filePath: string;
+  values: Record<string, string>;
+}
+
+/**
+ * Read `.secrets.yaml` from a directory, register every value with the
+ * global SecretRegistry, and return the parsed map. Returns `null` when
+ * the file is absent — callers should treat that as "no secrets to
+ * register" rather than a failure.
+ */
+export function loadSecretsFile(dir: string): SecretsFile | null {
+  const filePath = join(dir, SECRETS_FILENAME);
+  if (!existsSync(filePath)) return null;
+  const text = readFileSync(filePath, "utf-8");
+  let parsed: unknown;
+  try {
+    parsed = (Bun as any).YAML.parse(text);
+  } catch (err) {
+    throw new Error(`Failed to parse ${filePath}: ${(err as Error).message}`);
+  }
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${filePath} must contain a flat YAML object of key: "value" entries`);
+  }
+
+  const values: Record<string, string> = {};
+  for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+    if (v == null) continue;                 // empty placeholder — skip
+    if (typeof v === "object") {
+      throw new Error(
+        `${filePath}: nested values are not supported (key "${k}"). ` +
+        `.secrets.yaml is intentionally flat — keep one level of key/value pairs.`,
+      );
+    }
+    values[k] = String(v);
+  }
+
+  const reg = getSecretRegistry();
+  reg.registerAll(values);
+
+  return { filePath, values };
+}
+
+/**
+ * Walk up a directory chain to find the first `.secrets.yaml` and load
+ * it. Used by the env loader so a single secrets file at the API root
+ * (`apis/<name>/.secrets.yaml`) is picked up regardless of which
+ * subdirectory `zond run` was invoked from.
+ */
+export function loadSecretsFromAncestor(start: string, stopAt?: string): SecretsFile | null {
+  let dir = start;
+  for (let i = 0; i < 8; i++) {
+    const file = loadSecretsFile(dir);
+    if (file) return file;
+    if (stopAt && dir === stopAt) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Resolve any `@secret:<name>` reference inside an env object against
+ * the values from `secrets`. Throws when a referenced name is missing
+ * (fail-loud).
+ */
+export function resolveSecretRefs(
+  envValues: Record<string, string>,
+  secrets: SecretsFile | null,
+  filePath: string,
+): Record<string, string> {
+  const out: Record<string, string> = { ...envValues };
+  for (const [k, v] of Object.entries(out)) {
+    const m = typeof v === "string" ? v.match(SECRET_REF_RE) : null;
+    if (!m) continue;
+    const refName = m[1]!;
+    const value = secrets?.values[refName];
+    if (value == null) {
+      const where = secrets ? secrets.filePath : `${dirname(filePath)}/${SECRETS_FILENAME}`;
+      throw new Error(
+        `${filePath}: key "${k}" references @secret:${refName} but no such entry exists in ${where}. ` +
+        `Add \`${refName}: "<value>"\` to ${where} (or remove the @secret: prefix to use a literal value).`,
+      );
+    }
+    out[k] = value;
+  }
+  return out;
+}