@kirrosh/zond 0.22.0 → 0.23.0

package/src/cli/commands/report.ts

@@ -0,0 +1,241 @@
+import { resolve } from "path";
+import { getDb } from "../../db/schema.ts";
+import {
+  getRunById,
+  getResultsByRunId,
+  getCollectionById,
+} from "../../db/queries.ts";
+import { renderHtmlReport } from "../../core/exporter/html-report/index.ts";
+import { loadCoverage } from "../../core/coverage/loader.ts";
+import type { CoverageMatrix } from "../../core/coverage/reasons.ts";
+import { printError, printWarning } from "../output.ts";
+import { applySanitizer } from "../../core/exporter/exporter.ts";
+import { loadIdentityFromAncestor, redactIdentityIn } from "../../core/identity/identity-file.ts";
+import { rotateOutputTarget } from "../../core/workspace/output-rotation.ts";
+import { resolveTriageOutput } from "../../core/workspace/triage-path.ts";
+import { recordGeneratedFile } from "../../core/workspace/manifest.ts";
+import { findWorkspaceRoot } from "../../core/workspace/root.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { VERSION } from "../version.ts";
+
+export interface ReportExportOptions {
+  runId: string;
+  output?: string;
+  api?: string;
+  dbPath?: string;
+  json?: boolean;
+  /** TASK-162 (m-9 P6): when true, overwrite existing target instead of
+   *  rotating it to <stem>-vN<ext>. */
+  overwrite?: boolean;
+  /** TASK-164 (m-9 P8): cap each request/response body to N bytes
+   *  (default 8192). Pass 0 to disable. */
+  bodyCapBytes?: number;
+  /** TASK-173 (m-10): replace every value from `.identity.yaml` with
+   *  `<identity:<key>>`. Off by default; opt-in for outbound shares. */
+  redactIdentity?: boolean;
+}
+
+/** TASK-164: shared default cap. ≤ 8 KB per body keeps SaaS-class
+ *  exports under ~150 KB while preserving the first page of every body. */
+const DEFAULT_BODY_CAP_BYTES = 8192;
+
+function parseRunId(raw: string): number | null {
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export async function reportExportHtmlCommand(
+  options: ReportExportOptions,
+): Promise<number> {
+  const runId = parseRunId(options.runId);
+  if (runId == null) {
+    const msg = `Invalid run-id: ${options.runId}. Expected a positive integer.`;
+    if (options.json) printJson(jsonError("report export --html", [msg]));
+    else printError(msg);
+    return 2;
+  }
+
+  try {
+    getDb(options.dbPath);
+  } catch (err) {
+    const msg = `Failed to open database: ${(err as Error).message}`;
+    if (options.json) printJson(jsonError("report export --html", [msg]));
+    else printError(msg);
+    return 2;
+  }
+
+  const run = getRunById(runId);
+  if (!run) {
+    const msg = `Run #${runId} not found. List runs with: zond db runs`;
+    if (options.json) printJson(jsonError("report export --html", [msg]));
+    else printError(msg);
+    return 1;
+  }
+
+  const results = getResultsByRunId(runId);
+  const collection = run.collection_id != null ? getCollectionById(run.collection_id) : null;
+
+  // Try to enrich with the spec-aware coverage matrix (TASK-109). Best-effort:
+  // skip silently if no API can be resolved or the spec can't load.
+  let coverageMatrix: CoverageMatrix | undefined;
+  const apiName = options.api ?? collection?.name ?? null;
+  if (apiName) {
+    try {
+      const cov = await loadCoverage({ apiName, runId });
+      coverageMatrix = cov.matrix;
+    } catch {
+      // No registered API / missing spec — fall back to URL-only coverage.
+    }
+  }
+
+  const html = renderHtmlReport({
+    run,
+    results,
+    zondVersion: VERSION,
+    generatedAt: new Date(),
+    collectionName: collection?.name ?? null,
+    bodyCapBytes: options.bodyCapBytes ?? DEFAULT_BODY_CAP_BYTES,
+    ...(coverageMatrix ? { coverageMatrix } : {}),
+  });
+
+  // TASK-163 (m-9 P7): default to triage/<api>/<run>/ when --output is
+  // missing or just a filename. Explicit dir paths are honoured verbatim.
+  const triage = resolveTriageOutput({
+    command: "html",
+    runId,
+    api: apiName,
+    ext: "html",
+    userOutput: options.output,
+  });
+  const outputPath = triage.absolute;
+  const rotation = rotateOutputTarget(outputPath, { overwrite: options.overwrite });
+
+  try {
+    // TASK-168 (m-10): defensive redact pass on the final HTML. Most data
+    // is already redacted at DB-write time (TASK-167), but if the user
+    // re-ran the same session they may have just registered a new value
+    // — wrap the export so it can never out-pace the registry.
+    let payload = applySanitizer(html);
+    if (options.redactIdentity && collection?.base_dir) {
+      const id = loadIdentityFromAncestor(collection.base_dir);
+      if (id) payload = redactIdentityIn(payload, id.values);
+    }
+    await Bun.write(outputPath, payload);
+    // TASK-156: register so `zond clean --all` later removes it.
+    try {
+      const ws = findWorkspaceRoot();
+      if (!ws.fromFallback) {
+        recordGeneratedFile(ws.root, {
+          path: outputPath,
+          by: "zond report export",
+          api: apiName ?? undefined,
+        });
+      }
+    } catch { /* best-effort */ }
+  } catch (err) {
+    const msg = `Failed to write report: ${(err as Error).message}`;
+    if (options.json) printJson(jsonError("report export --html", [msg]));
+    else printError(msg);
+    return 2;
+  }
+
+  const sizeKb = Math.round(new Blob([html]).size / 1024);
+  const warnings: string[] = [];
+  if (sizeKb > 2048) {
+    warnings.push(`Report is ${sizeKb} KB (>2 MB) — consider trimming response bodies before re-running`);
+  }
+  if (rotation.rotatedTo) {
+    warnings.push(`Previous report rotated to ${rotation.rotatedTo}`);
+  }
+
+  if (options.json) {
+    printJson(
+      jsonOk(
+        "report export --html",
+        {
+          runId,
+          output: outputPath,
+          sizeKb,
+          totalSteps: results.length,
+          failures: results.filter((r) => r.status !== "pass" && r.status !== "skip").length,
+        },
+        warnings,
+      ),
+    );
+  } else {
+    for (const w of warnings) printWarning(w);
+    const failures = results.filter((r) => r.status !== "pass" && r.status !== "skip").length;
+    // TASK-241: status → stderr; stdout carries only the artifact path so
+    // shells/agents can do `out=$(zond report export <id>)` without parsing.
+    process.stderr.write(
+      `zond: wrote ${sizeKb} KB (${results.length} step${results.length === 1 ? "" : "s"}, ${failures} failure${failures === 1 ? "" : "s"})\n`,
+    );
+    process.stdout.write(`${outputPath}\n`);
+  }
+
+  return 0;
+}
+
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+import { parsePositiveInt } from "../argv.ts";
+import { reportBundleCommand, type BundleArtifact } from "./report-bundle.ts";
+
+export function registerReport(program: Command): void {
+  const reportCmd = program.command("report").description("Export run reports for sharing");
+  reportCmd
+    .command("export <run-id>")
+    .description("Export a stored run as a single-file HTML report (shareable, openable in any browser)")
+    .option("--html", "Render as HTML (default and currently the only supported format)")
+    .option("-o, --output <file>", "Output file path (default: zond-run-<id>.html)")
+    .option("--api <name>", "Embed coverage map for this registered API (auto-detected from run.collection_id)")
+    .option("--db <path>", "Path to SQLite database file")
+    .option("--overwrite", "Overwrite existing --output file in place (default: rotate to <stem>-vN.<ext>)")
+    .option("--body-cap <n>", "Truncate request/response bodies to N bytes (default 8192). Set 0 / use --no-body-cap to disable.", parsePositiveInt("--body-cap"))
+    .option("--no-body-cap", "Keep full request/response bodies (overrides --body-cap)")
+    .option("--redact-identity", "Replace values from .identity.yaml with <identity:<key>> placeholders (for outbound sharing)")
+    .action(async (runId: string, opts, cmd: Command) => {
+      const bodyCapBytes = opts.bodyCap === false ? 0 : (typeof opts.bodyCap === "number" ? opts.bodyCap : undefined);
+      process.exitCode = await reportExportHtmlCommand({
+        runId,
+        output: opts.output,
+        api: opts.api,
+        dbPath: opts.db,
+        overwrite: opts.overwrite === true,
+        bodyCapBytes,
+        redactIdentity: opts.redactIdentity === true,
+        json: globalJson(cmd),
+      });
+    });
+
+  reportCmd
+    .command("bundle [range]")
+    .description("TASK-143: batch triage exporter — collect case-study + HTML report + diagnose JSON for a range of runs in one shot. <range> can be \"A..B\" (inclusive), \"A,B,C\" (list), or use --session <id>.")
+    .option("-o, --output <dir>", "Output directory (default: triage/bundle/<timestamp>/)")
+    .option("--session <id>", "Resolve runs by session_id instead of an explicit range")
+    .option(
+      "--include <artefacts>",
+      "Comma-separated subset of artefacts to write (default: all). One or more of: case-study, export, diagnose",
+      (val: string) => val.split(",").map(s => s.trim()).filter(Boolean),
+    )
+    .option("--db <path>", "Path to SQLite database file")
+    .option("--body-cap <n>", "Truncate request/response bodies to N bytes (default 8192). Pass 0 / use --no-body-cap to disable.", parsePositiveInt("--body-cap"))
+    .option("--no-body-cap", "Keep full request/response bodies (overrides --body-cap)")
+    .action(async (range: string | undefined, opts, cmd: Command) => {
+      const bodyCapBytes = opts.bodyCap === false ? 0 : (typeof opts.bodyCap === "number" ? opts.bodyCap : undefined);
+      const include = (opts.include as string[] | undefined)?.filter(
+        (a): a is BundleArtifact => a === "case-study" || a === "export" || a === "diagnose",
+      );
+      process.exitCode = await reportBundleCommand({
+        range,
+        sessionId: opts.session,
+        output: opts.output,
+        include,
+        dbPath: opts.db,
+        bodyCapBytes,
+        json: globalJson(cmd),
+      });
+    });
+
+}

package/src/cli/commands/request.ts

@@ -1,6 +1,81 @@
 import { sendAdHocRequest } from "../../core/runner/send-request.ts";
-import { printError } from "../output.ts";
-import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { printError, printSuccess, printWarning } from "../output.ts";
+import { jsonOk, jsonError, printJson, zerr } from "../json-envelope.ts";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { createSchemaValidator } from "../../core/runner/schema-validator.ts";
+import { readOpenApiSpec, extractEndpoints } from "../../core/generator/openapi-reader.ts";
+import { resolveCollectionSpec } from "../../core/setup-api.ts";
+import { findCollectionByNameOrId } from "../../db/queries.ts";
+import { getDb } from "../../db/schema.ts";
+import type { AssertionResult } from "../../core/runner/types.ts";
+
+// TASK-272: when the request fails authentication (401/403) and the user
+// did NOT pass `--api <name>`, surface a one-liner pointing at auto-auth via
+// `apis/<name>/.secrets.yaml`. Only fires if an apis/ workspace exists in cwd
+// (otherwise the hint is irrelevant). Also triggered when the headers contain a
+// literal unexpanded shell-substitution shape ($(…) or `…`) — a tell-tale of a
+// blocked-by-sandbox manual auth attempt.
+function detectApisWorkspace(cwd: string): string[] {
+  const apisDir = join(cwd, "apis");
+  if (!existsSync(apisDir)) return [];
+  try {
+    return readdirSync(apisDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+function looksLikeBlockedShellSubstitution(s: string | undefined): boolean {
+  if (!s) return false;
+  // unexpanded `$(...)` or backtick `...` with a likely secret-fetching command
+  return /\$\([^)]+\)|`[^`]+`/.test(s) && /yq|cat|jq|grep|awk|sed|sh /.test(s);
+}
+
+/** ARV-110 / ARV-144: pretty-print --json-path failure to stderr.
+ *  Two distinct hints depending on the failure:
+ *  - top-level array (reason starts with "expected an array index"):
+ *    user wrote `data[0].id` against a body that's already an array →
+ *    suggest `[0].id` / `0.id`.
+ *  - envelope confusion (firstSeg in body/data, resolved is empty):
+ *    user came from `--json | jq .data.body.id` and forgot that --json-path
+ *    addresses the response body, not the envelope. */
+function printJsonPathDiagnostic(
+  jsonPath: string | undefined,
+  diag: { resolved: string[]; failedAt?: string; reason?: string } | undefined,
+): void {
+  if (!jsonPath || !diag?.failedAt) return;
+  const resolved = diag.resolved.length > 0 ? diag.resolved.join(".") : "(root)";
+  process.stderr.write(
+    `zond: --json-path '${jsonPath}' did not resolve — stopped at segment "${diag.failedAt}" after ${resolved}: ${diag.reason ?? "unknown"}\n`,
+  );
+  const firstSeg = jsonPath.replace(/\[\d+\]/g, "").split(".")[0];
+  const isArrayMismatch = diag.resolved.length === 0 && /^expected an array index/.test(diag.reason ?? "");
+  if (isArrayMismatch) {
+    const tail = jsonPath.replace(/^[^.[]+/, "");
+    const suggestion = tail ? `[0]${tail.startsWith(".") || tail.startsWith("[") ? tail : "." + tail}` : "[0]";
+    process.stderr.write(
+      `      Hint: response body is a top-level array — use \`--json-path '${suggestion}'\` or \`--json-path '0${tail}'\` to index it.\n`,
+    );
+    return;
+  }
+  if ((firstSeg === "body" || firstSeg === "data") && diag.resolved.length === 0) {
+    process.stderr.write(
+      `      Hint: --json-path extracts from the response body, not the zond envelope. ` +
+      `To address the envelope's data.body.id, use \`--json\` and pipe to jq.\n`,
+    );
+  }
+}
+
+function authHintLines(apis: string[]): string[] {
+  const example = apis[0] ?? "<name>";
+  return [
+    `Hint: pass \`--api ${example}\` to auto-load Authorization from apis/${example}/.secrets.yaml`,
+    `      (avoids manual "$(yq ...)" shell substitution and keeps secrets out of shell history).`,
+  ];
+}
 
 export interface RequestOptions {
   method: string;
@@ -13,6 +88,23 @@ export interface RequestOptions {
   jsonPath?: string;
   dbPath?: string;
   json?: boolean;
+  /** TASK-142: validate the response body against the OpenAPI response schema. */
+  validateSchema?: boolean;
+  /** TASK-142: explicit "METHOD:/path" override when path-templating heuristics
+   *  fail or the user wants to validate against a different endpoint. */
+  validateAgainst?: string;
+  /** ARV-149: send the body as `application/x-www-form-urlencoded` (Stripe v1
+   *  style). When omitted but `--api` is set, zond auto-detects from the
+   *  spec's requestBody.content. */
+  form?: boolean;
+}
+
+interface SchemaValidationOutcome {
+  status: "PASS" | "FAIL" | "no-spec" | "no-endpoint" | "no-schema";
+  matchedEndpoint: { method: string; path: string } | null;
+  matchedResponseStatus: string | null;
+  errors: AssertionResult[];
+  message?: string;
 }
 
 export async function requestCommand(options: RequestOptions): Promise<number> {
@@ -27,6 +119,15 @@ export async function requestCommand(options: RequestOptions): Promise<number> {
       }
     }
 
+    // ARV-149: when --form is not set but --api is, peek at the spec to see
+    // whether the matching endpoint declares only application/x-www-form-urlencoded
+    // (Stripe v1 pattern). If so, default to form encoding so users don't get
+    // a 400 "wrong content type" on every POST against form-only APIs.
+    let useForm = options.form === true;
+    if (!useForm && options.api) {
+      useForm = await detectFormFromSpec(options).catch(() => false);
+    }
+
     const result = await sendAdHocRequest({
       method: options.method.toUpperCase(),
       url: options.url,
@@ -37,21 +138,295 @@ export async function requestCommand(options: RequestOptions): Promise<number> {
       collectionName: options.api,
       jsonPath: options.jsonPath,
       dbPath: options.dbPath,
+      form: useForm,
     });
 
+    let validation: SchemaValidationOutcome | null = null;
+    if (options.validateSchema || options.validateAgainst) {
+      validation = await runSchemaValidation(options, result);
+    }
+
     if (options.json) {
-      printJson(jsonOk("request", result));
+      printJson(jsonOk("request", validation ? { ...result, schema_validation: validation } : result));
+      // ARV-110: surface jsonPath diagnostic on stderr in --json mode too, so
+      // pipelines that read envelope from stdout still see *why* `body` came
+      // back null. Without this, the only signal was a silent null inside the
+      // envelope — easy to misread as "envelope shape differs between modes".
+      printJsonPathDiagnostic(options.jsonPath, result.jsonPathDiagnostic);
+    } else if (options.jsonPath) {
+      // TASK-133: pipe-friendly mode — print only the extracted value.
+      // Scalars (string/number/bool) emit verbatim with no JSON quoting so
+      // shells can use the output directly (e.g. `id=$(zond request … --json-path data.id)`).
+      // null/undefined → empty line. Objects/arrays → compact JSON.
+      const v = result.body;
+      if (v === null || v === undefined) {
+        console.log("");
+        printJsonPathDiagnostic(options.jsonPath, result.jsonPathDiagnostic);
+      } else if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+        console.log(String(v));
+      } else {
+        console.log(JSON.stringify(v));
+      }
+      if (validation) printSchemaValidation(validation);
     } else {
       console.log(JSON.stringify(result, null, 2));
+      if (validation) printSchemaValidation(validation);
     }
+
+    // TASK-272: post-response auto-auth hint on 401/403 without --api
+    if (
+      !options.json
+      && (result.status === 401 || result.status === 403)
+      && !options.api
+    ) {
+      const apis = detectApisWorkspace(process.cwd());
+      if (apis.length > 0) {
+        for (const line of authHintLines(apis)) console.error(line);
+      }
+    }
+    if (validation && validation.status === "FAIL") return 1;
     return 0;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     if (options.json) {
-      printJson(jsonError("request", [message]));
+      const code = /not registered/.test(message) ? "api_not_registered" : "unknown_error";
+      printJson(jsonError("request", [zerr(code, message)]));
     } else {
       printError(message);
+      // TASK-272: if the failure is shaped like blocked shell-substitution in
+      // body/header (sandbox refused to expand `$(yq ...)`), point users at
+      // `--api <name>` auto-auth instead.
+      const headerBlob = (options.headers ?? []).join("\n");
+      if (
+        !options.api
+        && (looksLikeBlockedShellSubstitution(options.body) || looksLikeBlockedShellSubstitution(headerBlob))
+      ) {
+        const apis = detectApisWorkspace(process.cwd());
+        if (apis.length > 0) {
+          for (const line of authHintLines(apis)) console.error(line);
+        }
+      }
     }
     return 1;
   }
 }
+
+// ──────────────────────────────────────────────
+// TASK-142: --validate-schema / --validate-against
+// ──────────────────────────────────────────────
+
+async function runSchemaValidation(
+  options: RequestOptions,
+  result: { status: number; body: unknown },
+): Promise<SchemaValidationOutcome> {
+  if (!options.api) {
+    return {
+      status: "no-spec",
+      matchedEndpoint: null,
+      matchedResponseStatus: null,
+      errors: [],
+      message: "schema validation requires --api <name> (the spec is loaded from the registered collection)",
+    };
+  }
+
+  getDb(options.dbPath);
+  const col = findCollectionByNameOrId(options.api);
+  if (!col?.openapi_spec) {
+    return {
+      status: "no-spec",
+      matchedEndpoint: null,
+      matchedResponseStatus: null,
+      errors: [],
+      message: `collection '${options.api}' has no openapi_spec — register one with \`zond add api ${options.api} --spec <path>\``,
+    };
+  }
+
+  let doc;
+  try {
+    doc = await readOpenApiSpec(resolveCollectionSpec(col.openapi_spec));
+  } catch (err) {
+    return {
+      status: "no-spec",
+      matchedEndpoint: null,
+      matchedResponseStatus: null,
+      errors: [],
+      message: `failed to load OpenAPI spec: ${(err as Error).message}`,
+    };
+  }
+
+  let method: string;
+  let path: string;
+  if (options.validateAgainst) {
+    const parsed = parseMethodPathArg(options.validateAgainst);
+    if (!parsed) {
+      return {
+        status: "no-endpoint",
+        matchedEndpoint: null,
+        matchedResponseStatus: null,
+        errors: [],
+        message: `--validate-against expects "METHOD:/path" (e.g. "GET:/users/{id}"), got: ${options.validateAgainst}`,
+      };
+    }
+    method = parsed.method;
+    path = parsed.path;
+  } else {
+    method = options.method.toUpperCase();
+    path = extractPath(options.url);
+  }
+
+  const validator = createSchemaValidator(doc);
+  const inspect = validator.inspect(method, path, result.status);
+
+  if (!inspect.matchedEndpoint) {
+    return {
+      status: "no-endpoint",
+      matchedEndpoint: null,
+      matchedResponseStatus: null,
+      errors: [],
+      message: `no spec endpoint matches ${method} ${path}. Pass \`--validate-against "METHOD:/path"\` (use spec template form, e.g. "GET:/users/{id}") to override.`,
+    };
+  }
+  if (!inspect.hasJsonSchema) {
+    return {
+      status: "no-schema",
+      matchedEndpoint: inspect.matchedEndpoint,
+      matchedResponseStatus: inspect.matchedResponseStatus,
+      errors: [],
+      message: `endpoint ${inspect.matchedEndpoint.method} ${inspect.matchedEndpoint.path} has no application/json schema for status ${result.status} (matched branch: ${inspect.matchedResponseStatus ?? "none"})`,
+    };
+  }
+
+  const errors = validator.validate(method, path, result.status, result.body);
+  return {
+    status: errors.length === 0 ? "PASS" : "FAIL",
+    matchedEndpoint: inspect.matchedEndpoint,
+    matchedResponseStatus: inspect.matchedResponseStatus,
+    errors,
+  };
+}
+
+function printSchemaValidation(v: SchemaValidationOutcome): void {
+  const ep = v.matchedEndpoint ? `${v.matchedEndpoint.method} ${v.matchedEndpoint.path}` : "—";
+  const branch = v.matchedResponseStatus ?? "—";
+  console.log("");
+  console.log(`Schema validation: ${v.status}`);
+  console.log(`  endpoint:        ${ep}`);
+  console.log(`  response branch: ${branch}`);
+  if (v.message) console.log(`  ${v.message}`);
+  if (v.status === "FAIL") {
+    for (const e of v.errors) {
+      console.log(`  • ${e.field} — ${e.rule}: ${e.expected}`);
+    }
+  }
+  if (v.status === "no-endpoint" || v.status === "no-spec" || v.status === "no-schema") {
+    printWarning(v.message ?? `validation skipped: ${v.status}`);
+  } else if (v.status === "PASS") {
+    printSuccess("response body matches the response schema");
+  }
+}
+
+function parseMethodPathArg(raw: string): { method: string; path: string } | null {
+  const m = raw.match(/^\s*([A-Za-z]+)\s*[: ]\s*(\/.*?)\s*$/);
+  if (!m) return null;
+  return { method: m[1]!.toUpperCase(), path: m[2]! };
+}
+
+/** ARV-149: peek at the OpenAPI spec for the matching endpoint and return
+ *  true when its requestBody declares only application/x-www-form-urlencoded
+ *  (no JSON variant). Cheap-failing — any spec/db error returns false so the
+ *  caller falls back to the JSON default. */
+async function detectFormFromSpec(options: RequestOptions): Promise<boolean> {
+  if (!options.api || !options.body) return false;
+  getDb(options.dbPath);
+  const col = findCollectionByNameOrId(options.api);
+  if (!col?.openapi_spec) return false;
+  const doc = await readOpenApiSpec(resolveCollectionSpec(col.openapi_spec));
+  const endpoints = extractEndpoints(doc);
+  const method = options.method.toUpperCase();
+  const path = extractPath(options.url);
+  // The OpenAPI reader normalises requestBodyContentType (prefers JSON when
+  // present, otherwise records the first declared content type). For a true
+  // form-only endpoint that field is "application/x-www-form-urlencoded".
+  const exact = endpoints.find(e => e.method.toUpperCase() === method && e.path === path);
+  const matched = exact ?? endpoints.find(e => {
+    if (e.method.toUpperCase() !== method) return false;
+    const re = new RegExp(
+      "^" + e.path.replace(/\{[^}]+\}/g, "[^/]+").replace(/\//g, "\\/") + "$",
+    );
+    return re.test(path);
+  });
+  return matched?.requestBodyContentType === "application/x-www-form-urlencoded";
+}
+
+function extractPath(url: string): string {
+  // Absolute URL → use URL parser. Relative URL ("/users/1") → use as-is.
+  if (/^https?:\/\//i.test(url)) {
+    try {
+      return new URL(url).pathname;
+    } catch {
+      return url;
+    }
+  }
+  // Strip query string from relative paths.
+  const q = url.indexOf("?");
+  return q >= 0 ? url.slice(0, q) : url;
+}
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+import { collect, parsePositiveInt } from "../argv.ts";
+import { getApi } from "../util/api-context.ts";
+import { loadEnvMeta } from "../../core/parser/variables.ts";
+import { resolveTimeoutMs } from "../../core/workspace/config.ts";
+
+export function registerRequest(program: Command): void {
+  program
+    .command("request <method> <url>")
+    .description("Send an ad-hoc HTTP request")
+    .option("--header <H>", `Request header "Name: Value" (repeatable)`, collect, [])
+    .option("--body <json>", "Request body (JSON string)")
+    .option("--timeout <ms>", "Request timeout (overrides apis/<name>/.env.yaml `timeoutMs` and zond.config.yml `defaults.timeout_ms`; default 30000)", parsePositiveInt("--timeout"))
+    .option("--env <name>", "Environment for variable interpolation")
+    .option("--api <name>", "Collection name; auto-loads env + Authorization from apis/<name>/.secrets.yaml")
+    .option(
+      "--json-path <path>",
+      "Extract one field from the RESPONSE BODY (not the zond envelope; " +
+      "to address envelope.data.body.id pipe `--json` through jq instead). " +
+      "Dot notation, e.g. 'data.id', 'items[0].name'. For top-level array " +
+      "responses use '[0].id' or '0.id'. Without --json, prints " +
+      "the value verbatim — scalars without quotes for shell use " +
+      "(`id=$(zond request --json-path data.id ...)`), objects/arrays as compact JSON. " +
+      "With --json, embeds the extracted value as the envelope's `body` field.",
+    )
+    .option("--db <path>", "Path to SQLite database file")
+    .option("--validate-schema", "TASK-142: validate the response body against the OpenAPI response schema (requires --api). Endpoint is auto-resolved from the request method + URL.path; templated paths like /users/{id} are matched via regex. Falls back gracefully if no endpoint matches — pass --validate-against to override.")
+    .option("--validate-against <method:path>", "TASK-142: explicit endpoint override for --validate-schema, e.g. \"GET:/users/{id}\". Use the spec template form (with \"{...}\" placeholders).")
+    .option("--form", "ARV-149: send --body as application/x-www-form-urlencoded (Stripe v1, Rails/PHP-style APIs). Parses --body as JSON to lift fields, re-encodes with bracket notation. Auto-detected when --api is set and the spec endpoint declares only the form content type.")
+    .action(async (method: string, url: string, opts, cmd: Command) => {
+      const headers = (opts.header as string[] | undefined)?.length ? (opts.header as string[]) : undefined;
+      // ARV-53.
+      const api = getApi(cmd, opts);
+      let envTimeout: number | undefined;
+      if (api) {
+        try {
+          envTimeout = (await loadEnvMeta(opts.env, `apis/${api}`)).timeoutMs;
+        } catch { /* meta is best-effort */ }
+      }
+      const timeout = resolveTimeoutMs(opts.timeout, envTimeout);
+      process.exitCode = await requestCommand({
+        method,
+        url,
+        headers,
+        body: opts.body,
+        timeout,
+        env: opts.env,
+        api,
+        jsonPath: opts.jsonPath,
+        dbPath: opts.db,
+        json: globalJson(cmd),
+        validateSchema: opts.validateSchema === true || typeof opts.validateAgainst === "string",
+        validateAgainst: opts.validateAgainst,
+        form: opts.form === true,
+      });
+    });
+}