@kirrosh/zond 0.22.0 → 0.23.0

package/src/core/probe/orphan-tracker.ts

@@ -0,0 +1,188 @@
+/**
+ * TASK-278: persist «probe created this resource and DELETE failed» records to
+ * `~/.zond/orphans/<api>/<run-id>.jsonl` so `zond cleanup --orphans` can
+ * retry the deletion later — without re-running the probe.
+ *
+ * One JSON object per line for forward-compatible streaming reads. We never
+ * rewrite existing lines; cleanup-success appends a new `removed: true`
+ * record that supersedes the original one (loadOrphans collapses
+ * supersessions in memory so the on-disk file is append-only and crash-safe).
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, readdir, readFile, appendFile } from "node:fs/promises";
+import type { SecurityVerdict } from "./security-probe.ts";
+
+export interface OrphanRecord {
+  api: string;
+  runId: string;
+  /** ISO timestamp of the cleanup-attempt that produced this record. */
+  createdAt: string;
+  /** Method/path of the *creating* endpoint (e.g. POST /teams/). */
+  method: string;
+  path: string;
+  /** Captured id of the leaked resource (slug/uuid/numeric id). */
+  id: string;
+  /** Concrete DELETE URL path with the id already substituted. */
+  deletePath: string;
+  /** Last DELETE status zond observed; `null` for network errors. */
+  lastCleanupStatus: number | null;
+  /** Last error string (network message or HTTP-status sentence). */
+  lastCleanupError: string | null;
+  /** When true, this record cancels a prior orphan with the same
+   *  (api, runId, deletePath, id) tuple. Used by `cleanup --orphans` to
+   *  mark replayed-and-now-gone resources. */
+  removed?: boolean;
+  /** ARV-102 (F7): probe knew the resource was created but couldn't
+   *  derive a DELETE plan (response had no usable id, or the spec has no
+   *  DELETE counterpart for the create endpoint). The record is still
+   *  worth keeping so `cleanup --orphans` can surface "manual cleanup
+   *  required" — DELETE retry isn't possible, but the user must know.
+   *  When set, deletePath / id may be empty and `lastCleanupError`
+   *  carries the reason from the probe (e.g. "cleanup skipped: response
+   *  had no usable id"). */
+  requires_manual_cleanup?: boolean;
+}
+
+export function orphansRoot(): string {
+  return process.env.ZOND_ORPHANS_DIR ?? join(homedir(), ".zond", "orphans");
+}
+
+function recordFile(api: string, runId: string): string {
+  return join(orphansRoot(), api, `${runId}.jsonl`);
+}
+
+export async function appendOrphanRecord(record: OrphanRecord): Promise<void> {
+  const file = recordFile(record.api, record.runId);
+  await mkdir(join(orphansRoot(), record.api), { recursive: true });
+  await appendFile(file, JSON.stringify(record) + "\n", "utf-8");
+}
+
+/**
+ * Snapshot a probe-run's verdicts into the orphans store. We persist EVERY
+ * cleanup attempt that has a known id (regardless of success) so a SIGINT
+ * mid-run still leaves a trace of created resources. Successful DELETEs are
+ * written with `lastCleanupStatus` in 2xx — `loadOrphans` will treat them as
+ * already-removed and skip them.
+ */
+export async function persistVerdictsAsOrphans(api: string, runId: string, verdicts: SecurityVerdict[]): Promise<number> {
+  let written = 0;
+  for (const v of verdicts) {
+    const c = v.cleanup;
+    if (!c?.attempted) continue;
+    // ARV-102 (F7): pre-fix this branch dropped any verdict whose
+    // cleanup had no usable id OR no DELETE path (e.g. "no DELETE
+    // counterpart for POST /symbol-sources/", "response had no usable
+    // id"). Probe digest still counted these as cleanup-failures, but
+    // they never reached the orphan registry — `cleanup --orphans` then
+    // reported zero, hiding live API leakage. Now we persist a
+    // `requires_manual_cleanup: true` record so the operator at least
+    // sees "5 resources need manual cleanup".
+    const haveDeletePlan = c.id !== undefined && !!c.deletePath;
+    if (!haveDeletePlan) {
+      const record: OrphanRecord = {
+        api,
+        runId,
+        createdAt: new Date().toISOString(),
+        method: v.method.toUpperCase(),
+        path: v.path,
+        id: c.id !== undefined ? String(c.id) : "",
+        deletePath: c.deletePath ?? "",
+        lastCleanupStatus: c.status ?? null,
+        lastCleanupError: c.error ?? "cleanup skipped: no DELETE plan",
+        requires_manual_cleanup: true,
+      };
+      await appendOrphanRecord(record);
+      written++;
+      continue;
+    }
+    const removed = c.status != null && c.status >= 200 && c.status < 300;
+    const record: OrphanRecord = {
+      api,
+      runId,
+      createdAt: new Date().toISOString(),
+      method: v.method.toUpperCase(),
+      path: v.path,
+      id: String(c.id),
+      deletePath: c.deletePath ?? "",
+      lastCleanupStatus: c.status ?? null,
+      lastCleanupError: c.error ?? null,
+      ...(removed ? { removed: true } : {}),
+    };
+    await appendOrphanRecord(record);
+    written++;
+  }
+  return written;
+}
+
+/**
+ * Read every orphan file (optionally filtered by `--api` and `--run`) and
+ * return the surviving records — i.e. those NOT yet superseded by a
+ * `removed: true` follow-up.
+ */
+export async function loadOrphans(filter: { api?: string; runId?: string } = {}): Promise<OrphanRecord[]> {
+  const root = orphansRoot();
+  const apis: string[] = [];
+  try {
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory() && (!filter.api || e.name === filter.api)) apis.push(e.name);
+    }
+  } catch {
+    return [];
+  }
+
+  const out: OrphanRecord[] = [];
+  for (const api of apis) {
+    const dir = join(root, api);
+    let files: string[] = [];
+    try {
+      files = (await readdir(dir)).filter(f => f.endsWith(".jsonl"));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      const runId = f.replace(/\.jsonl$/, "");
+      if (filter.runId && runId !== filter.runId) continue;
+      const file = join(dir, f);
+      let raw: string;
+      try {
+        raw = await readFile(file, "utf-8");
+      } catch {
+        continue;
+      }
+      // De-dup: later records on the same (api, runId, deletePath, id) win.
+      // `removed: true` cancels the entry; non-removed records keep the
+      // most recent cleanup status / error.
+      // ARV-102 (F7): manual-only records (requires_manual_cleanup) often
+      // have empty deletePath / id (probe couldn't derive them), so the
+      // standard key would collapse all of them onto a single bucket.
+      // Fold method/path into the key for that branch — every distinct
+      // (method, path) on which probe gave up survives independently.
+      const byKey = new Map<string, OrphanRecord>();
+      for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const r = JSON.parse(trimmed) as OrphanRecord;
+          const key = r.requires_manual_cleanup
+            ? `${r.api}|${r.runId}|manual|${r.method}|${r.path}|${r.id}`
+            : `${r.api}|${r.runId}|${r.deletePath}|${r.id}`;
+          if (r.removed) {
+            byKey.delete(key);
+          } else {
+            byKey.set(key, r);
+          }
+        } catch {
+          // Skip malformed lines — best-effort parse.
+        }
+      }
+      for (const r of byKey.values()) out.push(r);
+    }
+  }
+  return out;
+}
+
+export async function markRemoved(record: OrphanRecord): Promise<void> {
+  await appendOrphanRecord({ ...record, removed: true, lastCleanupStatus: 200, lastCleanupError: null, createdAt: new Date().toISOString() });
+}

package/src/core/probe/path-discovery.ts

@@ -0,0 +1,440 @@
+/**
+ * Path-param fixture auto-discovery (TASK-92).
+ *
+ * Live probe runtime hook: before marking an endpoint as skipped because
+ * `.env.yaml` doesn't supply a value for a path placeholder
+ * (e.g. `/domains/{domain_id}` without `domain_id` in env), try to find a
+ * sibling list endpoint (`GET /domains`), call it once per run, and extract
+ * `data[0].id` (or compatible shape). Result cached per `GET listPath`.
+ *
+ * Failure modes (returned as `miss`, not exception):
+ *   • no `GET <listPath>` in spec
+ *   • list returned non-2xx
+ *   • list response has no extractable id
+ *   • list returned an empty array
+ *   • listPath itself depends on unresolved params we couldn't discover
+ */
+import type { EndpointInfo, SecuritySchemeInfo } from "../generator/types.ts";
+import { executeRequest } from "../runner/http-client.ts";
+import { substituteString } from "../parser/variables.ts";
+import { convertPath, captureFieldFor, liveAuthHeaders } from "./shared.ts";
+
+export type DiscoveryHit = { kind: "hit"; values: Record<string, string> };
+export type DiscoveryMiss = { kind: "miss"; reason: string };
+export type DiscoveryResult = DiscoveryHit | DiscoveryMiss;
+
+export interface DiscoveryCache {
+  /** key = `GET ${listPath}` (raw, with {placeholders}) */
+  results: Map<string, DiscoveryResult>;
+  /** keys currently being resolved — used to break cycles. */
+  inFlight: Set<string>;
+}
+
+export function createDiscoveryCache(): DiscoveryCache {
+  return { results: new Map(), inFlight: new Set() };
+}
+
+export interface DiscoverOptions {
+  ep: EndpointInfo;
+  unresolved: string[];
+  allEndpoints: EndpointInfo[];
+  schemes: SecuritySchemeInfo[];
+  vars: Record<string, string>;
+  cache: DiscoveryCache;
+  timeoutMs?: number;
+}
+
+export async function discoverPathParams(opts: DiscoverOptions): Promise<DiscoveryResult> {
+  const discovered: Record<string, string> = {};
+  for (const name of opts.unresolved) {
+    const listPath = parentCollectionPath(opts.ep.path, name);
+    if (!listPath) {
+      return { kind: "miss", reason: `cannot derive list-path for {${name}} from ${opts.ep.path}` };
+    }
+    const result = await discoverFromList({
+      paramName: name,
+      listPath,
+      allEndpoints: opts.allEndpoints,
+      schemes: opts.schemes,
+      vars: { ...opts.vars, ...discovered },
+      cache: opts.cache,
+      timeoutMs: opts.timeoutMs,
+    });
+    if (result.kind === "miss") return result;
+    Object.assign(discovered, result.values);
+  }
+  return { kind: "hit", values: discovered };
+}
+
+interface DiscoverFromListOpts {
+  paramName: string;
+  listPath: string;
+  allEndpoints: EndpointInfo[];
+  schemes: SecuritySchemeInfo[];
+  vars: Record<string, string>;
+  cache: DiscoveryCache;
+  timeoutMs?: number;
+}
+
+async function discoverFromList(opts: DiscoverFromListOpts): Promise<DiscoveryResult> {
+  const cacheKey = `GET ${opts.listPath}`;
+  const cached = opts.cache.results.get(cacheKey);
+  if (cached) {
+    if (cached.kind === "hit") {
+      const v = pickValue(cached.values);
+      if (v !== undefined) return { kind: "hit", values: { [opts.paramName]: v } };
+      return { kind: "miss", reason: `cached list ${opts.listPath} has no usable id` };
+    }
+    return cached;
+  }
+  if (opts.cache.inFlight.has(cacheKey)) {
+    return { kind: "miss", reason: `cycle detected resolving ${opts.listPath}` };
+  }
+
+  const listEp = opts.allEndpoints.find(
+    e => e.method.toUpperCase() === "GET" && e.path === opts.listPath && !e.deprecated,
+  );
+  if (!listEp) {
+    const miss: DiscoveryMiss = { kind: "miss", reason: `no GET ${opts.listPath} in spec` };
+    opts.cache.results.set(cacheKey, miss);
+    return miss;
+  }
+
+  opts.cache.inFlight.add(cacheKey);
+  try {
+    // Resolve listEp's own path placeholders (nested-collection case).
+    const baseUrl = (opts.vars["base_url"] ?? "").replace(/\/+$/, "");
+    const templated = `${baseUrl}${convertPath(listEp.path)}`;
+    let urlVars = opts.vars;
+    let urlSubstituted = String(substituteString(templated, urlVars));
+    let stillUnresolved = collectUnresolved(urlSubstituted);
+    if (stillUnresolved.length > 0) {
+      const inner = await discoverPathParams({
+        ep: listEp,
+        unresolved: stillUnresolved,
+        allEndpoints: opts.allEndpoints,
+        schemes: opts.schemes,
+        vars: opts.vars,
+        cache: opts.cache,
+        timeoutMs: opts.timeoutMs,
+      });
+      if (inner.kind === "miss") {
+        const miss: DiscoveryMiss = {
+          kind: "miss",
+          reason: `parent of {${opts.paramName}} unresolved (${inner.reason})`,
+        };
+        opts.cache.results.set(cacheKey, miss);
+        return miss;
+      }
+      urlVars = { ...opts.vars, ...inner.values };
+      urlSubstituted = String(substituteString(templated, urlVars));
+      stillUnresolved = collectUnresolved(urlSubstituted);
+      if (stillUnresolved.length > 0) {
+        const miss: DiscoveryMiss = {
+          kind: "miss",
+          reason: `parent of {${opts.paramName}} unresolved after discovery: ${stillUnresolved.join(", ")}`,
+        };
+        opts.cache.results.set(cacheKey, miss);
+        return miss;
+      }
+    }
+
+    const url = appendLimitOne(urlSubstituted, listEp);
+    const headers: Record<string, string> = {
+      accept: "application/json",
+      ...liveAuthHeaders(listEp, opts.schemes, urlVars),
+    };
+
+    let resp;
+    try {
+      resp = await executeRequest(
+        { method: "GET", url, headers },
+        { timeout: opts.timeoutMs ?? 30000, retries: 0 },
+      );
+    } catch (err) {
+      const miss: DiscoveryMiss = {
+        kind: "miss",
+        reason: `GET ${opts.listPath} network error: ${err instanceof Error ? err.message : String(err)}`,
+      };
+      opts.cache.results.set(cacheKey, miss);
+      return miss;
+    }
+    if (resp.status < 200 || resp.status >= 300) {
+      const miss: DiscoveryMiss = {
+        kind: "miss",
+        reason: `GET ${opts.listPath} returned ${resp.status}`,
+      };
+      opts.cache.results.set(cacheKey, miss);
+      return miss;
+    }
+    const id = extractFirstId(resp.body_parsed ?? resp.body, listEp);
+    if (id === undefined) {
+      // Distinguish empty-list from has-items-but-no-id-shape.
+      const empty = isEmptyList(resp.body_parsed ?? resp.body);
+      const miss: DiscoveryMiss = {
+        kind: "miss",
+        reason: empty
+          ? `auto-discovery: GET ${opts.listPath} returned empty list`
+          : `GET ${opts.listPath} response has no extractable id`,
+      };
+      opts.cache.results.set(cacheKey, miss);
+      return miss;
+    }
+    const hit: DiscoveryHit = { kind: "hit", values: { [opts.paramName]: id } };
+    opts.cache.results.set(cacheKey, hit);
+    return hit;
+  } finally {
+    opts.cache.inFlight.delete(cacheKey);
+  }
+}
+
+/** Walk segments of `path`, return everything before the first `{paramName}` segment. */
+export function parentCollectionPath(path: string, paramName: string): string | undefined {
+  const segments = path.split("/");
+  const idx = segments.findIndex(seg => seg === `{${paramName}}`);
+  if (idx <= 0) return undefined;
+  return segments.slice(0, idx).join("/") || "/";
+}
+
+function collectUnresolved(url: string): string[] {
+  return Array.from(url.matchAll(/\{\{([^}]+)\}\}/g)).map(m => m[1]!);
+}
+
+function appendLimitOne(url: string, listEp: EndpointInfo): string {
+  const hasLimitParam = listEp.parameters.some(
+    p => p.in === "query" && (p.name === "limit" || p.name === "per_page" || p.name === "page_size"),
+  );
+  if (!hasLimitParam) return url;
+  const sep = url.includes("?") ? "&" : "?";
+  const name = listEp.parameters.find(
+    p => p.in === "query" && (p.name === "limit" || p.name === "per_page" || p.name === "page_size"),
+  )!.name;
+  return `${url}${sep}${name}=1`;
+}
+
+/**
+ * Body-FK auto-discovery (TASK-137).
+ *
+ * Mirror of `discoverPathParams` for body-level FK fields. probe-mass-assignment
+ * builds its baseline body from the spec; required FK fields like
+ * `audience_id` / `project_slug` get filled with `{{$randomString}}` and the
+ * server returns 4xx → INCONCLUSIVE-baseline. We can do better: scan the
+ * request schema for FK-named fields, find a likely list endpoint
+ * (`GET /audiences` for `audience_id`), call it once, cache the id.
+ *
+ * The map returned is **suffix-aware**: `*_slug` → `slug`, `*_uuid` → `uuid`,
+ * else `id`. This matches what the env-var name implies — the same rule
+ * `zond discover` (TASK-136) uses for its CLI flow.
+ */
+const BODY_FK_SUFFIXES = ["_id", "_uuid", "_slug", "_key"] as const;
+
+interface BodyFkField {
+  /** Variable / body-field name (e.g. `audience_id`). */
+  name: string;
+  /** Resource stem (e.g. `audience`). */
+  stem: string;
+  /** Field expected on response item (`id`/`slug`/`uuid`/`key`). */
+  preferredField: string;
+}
+
+function collectBodyFkFields(
+  schema: import("openapi-types").OpenAPIV3.SchemaObject | undefined,
+): BodyFkField[] {
+  if (!schema || !schema.properties) return [];
+  const required = new Set(schema.required ?? []);
+  const out: BodyFkField[] = [];
+  for (const name of Object.keys(schema.properties)) {
+    if (!required.has(name)) continue;
+    for (const suffix of BODY_FK_SUFFIXES) {
+      if (name.endsWith(suffix)) {
+        const stem = name.slice(0, -suffix.length);
+        if (!stem) break;
+        const preferredField = suffix === "_id" ? "id" : suffix.slice(1);
+        out.push({ name, stem, preferredField });
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/** Walk the spec for a likely list endpoint owning the given stem. We accept
+ *  collection-level GET on `/<stem>s`, `/<stem>`, or any path ending in those.
+ *  Skips path-templated lists (need parent context). */
+function findOwnerListEndpoint(
+  stem: string,
+  endpoints: EndpointInfo[],
+): EndpointInfo | undefined {
+  const candidates = [`${stem}s`, stem, stem.replace(/y$/, "ies"), stem.replace(/s$/, "")];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const re = new RegExp(`/${candidate}/?$`, "i");
+    const ep = endpoints.find(
+      e =>
+        e.method.toUpperCase() === "GET" &&
+        !e.deprecated &&
+        !e.path.includes("{") &&
+        re.test(e.path),
+    );
+    if (ep) return ep;
+  }
+  return undefined;
+}
+
+export interface BodyFkDiscoveryOptions {
+  ep: EndpointInfo;
+  allEndpoints: EndpointInfo[];
+  schemes: SecuritySchemeInfo[];
+  vars: Record<string, string>;
+  cache: DiscoveryCache;
+  timeoutMs?: number;
+}
+
+export interface BodyFkDiscoveryResult {
+  /** Discovered values to merge into vars (only when missing in vars). */
+  values: Record<string, string>;
+  /** Field names that look like FK but couldn't be resolved (with reason). */
+  misses: Array<{ field: string; reason: string }>;
+}
+
+export async function discoverBodyFkVars(
+  opts: BodyFkDiscoveryOptions,
+): Promise<BodyFkDiscoveryResult> {
+  const fields = collectBodyFkFields(opts.ep.requestBodySchema);
+  const values: Record<string, string> = {};
+  const misses: Array<{ field: string; reason: string }> = [];
+
+  for (const field of fields) {
+    if (opts.vars[field.name] !== undefined && opts.vars[field.name] !== "") {
+      // already supplied by the user — nothing to do.
+      continue;
+    }
+    const listEp = findOwnerListEndpoint(field.stem, opts.allEndpoints);
+    if (!listEp) {
+      misses.push({ field: field.name, reason: `no GET /<${field.stem}s> in spec` });
+      continue;
+    }
+
+    const cacheKey = `GET ${listEp.path}#${field.preferredField}`;
+    const cached = opts.cache.results.get(cacheKey);
+    if (cached) {
+      if (cached.kind === "hit" && cached.values[field.name] !== undefined) {
+        values[field.name] = cached.values[field.name]!;
+      } else if (cached.kind === "miss") {
+        misses.push({ field: field.name, reason: cached.reason });
+      }
+      continue;
+    }
+
+    const baseUrl = (opts.vars["base_url"] ?? "").replace(/\/+$/, "");
+    const url = `${baseUrl}${listEp.path}`;
+    const headers: Record<string, string> = {
+      accept: "application/json",
+      ...liveAuthHeaders(listEp, opts.schemes, opts.vars),
+    };
+
+    let resp;
+    try {
+      resp = await executeRequest(
+        { method: "GET", url, headers },
+        { timeout: opts.timeoutMs ?? 30000, retries: 0 },
+      );
+    } catch (err) {
+      const reason = `network error on GET ${listEp.path}: ${err instanceof Error ? err.message : String(err)}`;
+      opts.cache.results.set(cacheKey, { kind: "miss", reason });
+      misses.push({ field: field.name, reason });
+      continue;
+    }
+    if (resp.status < 200 || resp.status >= 300) {
+      const reason = `GET ${listEp.path} → ${resp.status}`;
+      opts.cache.results.set(cacheKey, { kind: "miss", reason });
+      misses.push({ field: field.name, reason });
+      continue;
+    }
+    const id = pickFieldFromBody(
+      resp.body_parsed ?? resp.body,
+      field.preferredField,
+    );
+    if (id === undefined) {
+      const reason = `GET ${listEp.path} response has no usable ${field.preferredField} field`;
+      opts.cache.results.set(cacheKey, { kind: "miss", reason });
+      misses.push({ field: field.name, reason });
+      continue;
+    }
+    opts.cache.results.set(cacheKey, { kind: "hit", values: { [field.name]: id } });
+    values[field.name] = id;
+  }
+
+  return { values, misses };
+}
+
+function pickFieldFromBody(body: unknown, preferred: string): string | undefined {
+  const tryItem = (item: unknown): string | undefined => {
+    if (!item || typeof item !== "object") return undefined;
+    const obj = item as Record<string, unknown>;
+    for (const key of [preferred, "id", "slug", "uuid", "key"]) {
+      if (key in obj) {
+        const v = obj[key];
+        if (typeof v === "string" || typeof v === "number") return String(v);
+      }
+    }
+    return undefined;
+  };
+  if (Array.isArray(body)) return tryItem(body[0]);
+  if (body && typeof body === "object") {
+    const obj = body as Record<string, unknown>;
+    for (const wrap of ["data", "items", "results", "records"]) {
+      const arr = obj[wrap];
+      if (Array.isArray(arr) && arr.length > 0) return tryItem(arr[0]);
+    }
+  }
+  return undefined;
+}
+
+/** Try several common SaaS list-response shapes. */
+function extractFirstId(body: unknown, listEp: EndpointInfo): string | undefined {
+  if (Array.isArray(body)) {
+    return idFromItem(body[0], listEp);
+  }
+  if (body && typeof body === "object") {
+    const obj = body as Record<string, unknown>;
+    for (const key of ["data", "items", "results", "records"]) {
+      const arr = obj[key];
+      if (Array.isArray(arr) && arr.length > 0) {
+        return idFromItem(arr[0], listEp);
+      }
+    }
+  }
+  return undefined;
+}
+
+function idFromItem(item: unknown, listEp: EndpointInfo): string | undefined {
+  if (!item || typeof item !== "object") return undefined;
+  const obj = item as Record<string, unknown>;
+  // Prefer "id"; fall back to first uuid-shaped field hinted by spec.
+  if (typeof obj["id"] === "string" || typeof obj["id"] === "number") {
+    return String(obj["id"]);
+  }
+  const hinted = captureFieldFor(listEp);
+  if (hinted in obj && (typeof obj[hinted] === "string" || typeof obj[hinted] === "number")) {
+    return String(obj[hinted]);
+  }
+  return undefined;
+}
+
+function isEmptyList(body: unknown): boolean {
+  if (Array.isArray(body)) return body.length === 0;
+  if (body && typeof body === "object") {
+    const obj = body as Record<string, unknown>;
+    for (const key of ["data", "items", "results", "records"]) {
+      const arr = obj[key];
+      if (Array.isArray(arr)) return arr.length === 0;
+    }
+  }
+  return false;
+}
+
+function pickValue(values: Record<string, string>): string | undefined {
+  for (const v of Object.values(values)) if (typeof v === "string") return v;
+  return undefined;
+}