@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/scripts/collect-sub-agent-outputs.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// Collect raw sub-agent outputs into the recommendations.json array consumed by
+// verify-and-regen. Sub-agent hosts often wrap JSON in prose or markdown fences,
+// so extraction is permissive while candidateRef coverage stays strict.
+
+import { readFile, readdir, stat, writeFile, mkdir } from "node:fs/promises";
+import { dirname, resolve, basename } from "node:path";
+
+const log = (...a) => console.error("[collect-sub-agent-outputs]", ...a);
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.inputs.length === 0 && !args.manifestPath) {
+    console.error(
+      "usage: node scripts/collect-sub-agent-outputs.mjs [--manifest briefs/manifest.json] <output-file-or-dir...> [--out recommendations.json] [--strict]",
+    );
+    process.exit(1);
+  }
+
+  const manifest = args.manifestPath
+    ? JSON.parse(await readFile(args.manifestPath, "utf-8"))
+    : null;
+  const expected = manifest ? readExpectedBriefs(manifest) : [];
+  const preResolvedRecords = manifest ? readPreResolvedRecords(manifest) : [];
+  const files = args.inputs.length > 0 ? await collectInputFiles(args.inputs) : [];
+  const collected = [];
+  const summary = {
+    files: files.length,
+    kept: 0,
+    abstained: 0,
+    parseFailed: 0,
+    nonObject: 0,
+    missingCandidateRef: 0,
+  };
+  const errors = [];
+
+  for (const file of files) {
+    const raw = await readFile(file, "utf-8");
+    const extracted = extractJsonValue(raw);
+    if (!extracted.ok) {
+      summary.parseFailed++;
+      const msg = `${file}: ${extracted.reason}`;
+      if (args.strict) errors.push(msg);
+      else log(`warn: ${msg}`);
+      continue;
+    }
+
+    const records = normalizeOutput(extracted.value);
+    if (records.length === 0) {
+      summary.nonObject++;
+      const msg = `${file}: JSON did not contain a recommendation or abstention object`;
+      if (args.strict) errors.push(msg);
+      else log(`warn: ${msg}`);
+      continue;
+    }
+
+    for (const record of records) {
+      const candidateRef =
+        record.candidateRef ?? inferCandidateRefFromFile(file, expected, records.length);
+      if (!candidateRef) {
+        summary.missingCandidateRef++;
+        errors.push(`${file}: output is missing candidateRef`);
+        continue;
+      }
+      collected.push({
+        sourcePath: file,
+        record: record.candidateRef ? record : { ...record, candidateRef },
+      });
+    }
+  }
+
+  let ordered = collected;
+  if (expected.length > 0) {
+    const byRef = new Map();
+    for (const item of collected) {
+      const ref = item.record.candidateRef;
+      if (!expected.some((b) => b.candidateRef === ref)) {
+        errors.push(`${item.sourcePath}: unknown candidateRef ${ref}`);
+        continue;
+      }
+      if (byRef.has(ref)) {
+        errors.push(`${item.sourcePath}: duplicate output for candidateRef ${ref}`);
+        continue;
+      }
+      byRef.set(ref, item);
+    }
+    const missing = expected.filter((b) => !byRef.has(b.candidateRef));
+    for (const b of missing) errors.push(`missing output for candidateRef ${b.candidateRef}`);
+    ordered = expected.map((b) => byRef.get(b.candidateRef)).filter(Boolean);
+  } else {
+    ordered = collected.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));
+  }
+
+  const records = [...preResolvedRecords, ...ordered.map((item) => item.record)];
+  summary.kept = records.filter((r) => r?.abstain !== true).length;
+  summary.abstained = records.filter((r) => r?.abstain === true).length;
+
+  if (errors.length > 0) {
+    for (const e of errors) log(`error: ${e}`);
+    process.exit(2);
+  }
+  if (records.length === 0) {
+    log("error: no recommendation or abstention records collected");
+    process.exit(2);
+  }
+
+  const serialized = JSON.stringify(records, null, 2) + "\n";
+  if (args.outPath) {
+    await mkdir(dirname(args.outPath), { recursive: true });
+    await writeFile(args.outPath, serialized, "utf-8");
+    log(`wrote ${serialized.length}B → ${args.outPath}`);
+  } else {
+    process.stdout.write(serialized);
+  }
+  log(
+    `done: ${summary.files} files, ${summary.kept} recommendation draft(s), ${summary.abstained} found no supported change, ${summary.parseFailed} parse failed, ${summary.nonObject} invalid output(s)`,
+  );
+}
+
+function parseArgs(argv) {
+  const out = { inputs: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--manifest") out.manifestPath = resolve(argv[++i]);
+    else if (a.startsWith("--manifest=")) out.manifestPath = resolve(a.slice("--manifest=".length));
+    else if (a === "--out") out.outPath = resolve(argv[++i]);
+    else if (a.startsWith("--out=")) out.outPath = resolve(a.slice("--out=".length));
+    else if (a === "--strict") out.strict = true;
+    else out.inputs.push(resolve(a));
+  }
+  return out;
+}
+
+async function collectInputFiles(paths) {
+  const out = [];
+  for (const p of paths) {
+    const s = await stat(p);
+    if (s.isDirectory()) out.push(...(await walkDir(p)));
+    else if (s.isFile()) out.push(p);
+  }
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
+async function walkDir(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (e.name.startsWith(".")) continue;
+    const p = resolve(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walkDir(p)));
+    else if (e.isFile()) out.push(p);
+  }
+  return out;
+}
+
+function readExpectedBriefs(manifest) {
+  if (!manifest || typeof manifest !== "object" || !Array.isArray(manifest.briefs)) {
+    throw new TypeError("manifest must contain a briefs array");
+  }
+  return manifest.briefs.map((b, i) => {
+    if (!b?.candidateRef) throw new TypeError(`manifest.briefs[${i}].candidateRef is required`);
+    return {
+      group: b.group ?? null,
+      index: b.index ?? i,
+      candidateRef: b.candidateRef,
+    };
+  });
+}
+
+function readPreResolvedRecords(manifest) {
+  if (!manifest || !Array.isArray(manifest.preResolvedRecords)) return [];
+  return manifest.preResolvedRecords.map((r, i) => {
+    if (!isRecordObject(r)) {
+      throw new TypeError(
+        `manifest.preResolvedRecords[${i}] must be a recommendation or no-recommendation record`,
+      );
+    }
+    if (!r.candidateRef) {
+      throw new TypeError(`manifest.preResolvedRecords[${i}].candidateRef is required`);
+    }
+    return r;
+  });
+}
+
+function extractJsonValue(raw) {
+  for (const block of extractFenceBlocks(raw)) {
+    const parsed = tryParseJson(block);
+    if (parsed.ok) return parsed;
+  }
+  const full = tryParseJson(raw);
+  if (full.ok) return full;
+  for (const span of findBalancedJsonSpans(raw)) {
+    const parsed = tryParseJson(span);
+    if (parsed.ok) return parsed;
+  }
+  return { ok: false, reason: "no valid JSON object or array found" };
+}
+
+function extractFenceBlocks(raw) {
+  const out = [];
+  const re = /```(?:json|JSON)?\s*\n([\s\S]*?)```/g;
+  let m;
+  while ((m = re.exec(raw)) !== null) out.push(m[1].trim());
+  return out;
+}
+
+function tryParseJson(raw) {
+  try {
+    return { ok: true, value: JSON.parse(raw.trim()) };
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+}
+
+function findBalancedJsonSpans(raw) {
+  const spans = [];
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch !== "{" && ch !== "[") continue;
+    const closeFor = ch === "{" ? "}" : "]";
+    const stack = [closeFor];
+    let inString = false;
+    let escape = false;
+    for (let j = i + 1; j < raw.length; j++) {
+      const c = raw[j];
+      if (inString) {
+        if (escape) escape = false;
+        else if (c === "\\") escape = true;
+        else if (c === '"') inString = false;
+        continue;
+      }
+      if (c === '"') {
+        inString = true;
+        continue;
+      }
+      if (c === "{") stack.push("}");
+      else if (c === "[") stack.push("]");
+      else if (c === "}" || c === "]") {
+        if (stack.at(-1) !== c) break;
+        stack.pop();
+        if (stack.length === 0) {
+          spans.push(raw.slice(i, j + 1));
+          i = j;
+          break;
+        }
+      }
+    }
+  }
+  return spans;
+}
+
+function normalizeOutput(value) {
+  const unwrapped = unwrapEnvelope(value);
+  if (Array.isArray(unwrapped)) return unwrapped.filter(isRecordObject);
+  if (isRecordObject(unwrapped)) return [unwrapped];
+  if (unwrapped && typeof unwrapped === "object") {
+    if (isRecordObject(unwrapped.recommendation)) return [unwrapped.recommendation];
+    if (Array.isArray(unwrapped.recommendations))
+      return unwrapped.recommendations.filter(isRecordObject);
+  }
+  return [];
+}
+
+function unwrapEnvelope(value) {
+  let current = value;
+  for (let depth = 0; depth < 2; depth++) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) return current;
+    if (Array.isArray(current.recommendations) || current.recommendation) return current;
+    const keys = Object.keys(current);
+    const envelopeKey = ["data", "result", "insights"].find(
+      (k) => keys.length === 1 && k in current,
+    );
+    if (!envelopeKey) return current;
+    current = current[envelopeKey];
+  }
+  return current;
+}
+
+function isRecordObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  if (value.abstain === true) return true;
+  return ["what", "why", "fix", "bucket", "affectedFiles", "citations"].some((k) => k in value);
+}
+
+function inferCandidateRefFromFile(file, expected, recordCount) {
+  if (recordCount !== 1 || expected.length === 0) return null;
+  if (expected.length === 1) return expected[0].candidateRef;
+  const name = basename(file);
+  const matches = expected.filter((b) => {
+    if (!b.group && b.index == null) return false;
+    const group = escapeRegExp(String(b.group ?? ""));
+    const index = escapeRegExp(String(b.index));
+    return new RegExp(`(?:^|[^A-Za-z0-9])${group}[-_.]?${index}(?:[^A-Za-z0-9]|$)`).test(name);
+  });
+  return matches.length === 1 ? matches[0].candidateRef : null;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+main().catch((err) => {
+  console.error("[collect-sub-agent-outputs] FAILED:", err.message);
+  console.error(err.stack);
+  process.exit(1);
+});

package/skills/craft/vercel-optimize/scripts/deep-dive.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+// Runs AFTER gate-investigations.mjs and BEFORE any sub-agent reads source.
+// Attaches per-candidate evidence.deepDive to gate.toLaunch + gate.platform.
+// Byte-stable apart from totalWallMs; each CLI query is isolated.
+
+import { readFile } from "node:fs/promises";
+import {
+  specsForCandidate,
+  mergeIntoEvidence,
+  SCANNER_KINDS,
+  TIME_WINDOW,
+} from "../lib/deep-dive.mjs";
+import { queryMetric, readProjectJson, resolveCommandScope } from "../lib/vercel.mjs";
+
+const SCHEMA_VERSION = "1.0";
+const log = (...a) => console.error("[deep-dive]", ...a);
+
+async function main() {
+  // --cwd is load-bearing: the Vercel CLI resolves project/team from cwd's
+  // .vercel/project.json. Outside the project, metric queries silently hit the
+  // wrong team and look like "no traffic". We hard-fail on mismatch below.
+  const positional = [];
+  let explicitCwd = null;
+  for (let i = 2; i < process.argv.length; i++) {
+    const a = process.argv[i];
+    if (a === "--cwd" && i + 1 < process.argv.length) {
+      explicitCwd = process.argv[++i];
+    } else if (a.startsWith("--cwd=")) {
+      explicitCwd = a.slice("--cwd=".length);
+    } else {
+      positional.push(a);
+    }
+  }
+  const mergedPath = positional[0];
+  const gatePath = positional[1];
+  if (!mergedPath || !gatePath) {
+    console.error(
+      "usage: node scripts/deep-dive.mjs <merged.json> <gate.json> [--cwd <project-dir>]",
+    );
+    process.exit(1);
+  }
+
+  const [merged, gate] = await Promise.all([
+    readFile(mergedPath, "utf-8").then(JSON.parse),
+    readFile(gatePath, "utf-8").then(JSON.parse),
+  ]);
+
+  if (explicitCwd) {
+    process.chdir(explicitCwd);
+    log(`cwd: ${process.cwd()} (via --cwd)`);
+  }
+
+  const link = await readProjectJson(process.cwd());
+  if (!link) {
+    console.error(
+      `[deep-dive] FATAL: cwd ${process.cwd()} has no .vercel/project.json or .vercel/repo.json.`,
+    );
+    console.error(
+      "         Re-run with --cwd <project-dir> pointing at the linked project, or cd into it first.",
+    );
+    console.error(
+      "         (The Vercel CLI resolves team/project from cwd; without a .vercel/ linkage every query returns empty rows for the wrong team.)",
+    );
+    process.exit(2);
+  }
+  if (merged.projectId && link.projectId !== merged.projectId) {
+    console.error("[deep-dive] FATAL: cwd .vercel/ links a different project than merged.json.");
+    console.error("         Re-run with --cwd <dir-linked-to-the-collected-project>.");
+    process.exit(2);
+  }
+  if (merged.orgId && link.orgId && link.orgId !== merged.orgId) {
+    console.error(
+      "[deep-dive] FATAL: cwd .vercel/ links the project to a different Vercel scope than signals.json.",
+    );
+    console.error(
+      "         Re-run with --cwd <dir-linked-to-the-collected-project>, or rerun collect-signals.mjs from the intended app directory.",
+    );
+    process.exit(2);
+  }
+  log(`cwd link OK (source ${link.source})`);
+
+  const commandScope = await resolveDeepDiveCommandScope(merged, link);
+  if (!commandScope.ok) {
+    console.error(
+      `[deep-dive] FATAL: could not resolve a CLI-safe Vercel scope (${commandScope.detail ?? commandScope.error ?? "unknown"}).`,
+    );
+    console.error(
+      "         Re-run collect-signals.mjs with the current skill, run `vercel switch <team>`, or re-link with `vercel link --yes --project <project> --team <team-slug>`.",
+    );
+    process.exit(2);
+  }
+  if (typeof commandScope.cliScope === "string" && /^(team|usr)_/.test(commandScope.cliScope)) {
+    console.error(
+      "[deep-dive] FATAL: commandScope.cliScope is a raw account ID, not a CLI-safe scope.",
+    );
+    console.error(
+      "         Re-run collect-signals.mjs with the current skill so deep-dive queries use the same team as the broad pass.",
+    );
+    process.exit(2);
+  }
+  const commandAccountId = commandScope.teamId ?? commandScope.userId ?? null;
+  if (commandAccountId && link.orgId && link.orgId !== commandAccountId) {
+    console.error(
+      "[deep-dive] FATAL: cwd .vercel/ links the project to a different Vercel scope than commandScope.",
+    );
+    console.error(
+      "         Re-run with --cwd <dir-linked-to-the-collected-project>, or rerun collect-signals.mjs from the intended app directory.",
+    );
+    process.exit(2);
+  }
+  const scope = commandScope.cliScope || undefined;
+  log(`command scope resolved (source=${commandScope.source}; scoped=${scope ? "yes" : "no"})`);
+
+  const toLaunch = Array.isArray(gate.toLaunch) ? gate.toLaunch : [];
+  const platform = Array.isArray(gate.platform) ? gate.platform : [];
+
+  log(
+    `enriching ${toLaunch.length} toLaunch + ${platform.length} platform candidate(s) (window=${TIME_WINDOW})`,
+  );
+
+  const t0 = Date.now();
+  const errors = [];
+
+  // Flatten {candidate, spec}, fire all CLI calls in one Promise.all, re-group.
+  // Avoids per-candidate sequentiality.
+  const allCandidates = [
+    ...toLaunch.map((c, i) => ({ c, group: "toLaunch", i })),
+    ...platform.map((c, i) => ({ c, group: "platform", i })),
+  ];
+
+  const flatJobs = [];
+  const skipNotes = new Map();
+
+  for (const entry of allCandidates) {
+    const specs = specsForCandidate(entry.c);
+    if (specs.length === 0) {
+      if (SCANNER_KINDS.has(entry.c.kind)) {
+        skipNotes.set(`${entry.group}:${entry.i}`, "scanner-driven (no deep-dive needed)");
+      } else if (entry.c.kind === "platform_fluid_compute") {
+        skipNotes.set(`${entry.group}:${entry.i}`, "reused from broad pass (fnStartTypeByRoute)");
+      } else {
+        skipNotes.set(`${entry.group}:${entry.i}`, `no deep-dive spec for kind=${entry.c.kind}`);
+      }
+      continue;
+    }
+    for (const spec of specs) {
+      flatJobs.push({ entry, spec });
+    }
+  }
+
+  // Cut CLI calls two ways: (1) extract per-route slices already collected in
+  // the broad pass; (2) dedupe identical queries across candidates (same route
+  // can fire multiple gates wanting the same metric).
+  let extractedFromBroadPass = 0;
+  let dedupedQueryHits = 0;
+  const broadPassResults = [];
+  const remainingJobs = [];
+  for (const job of flatJobs) {
+    const extracted = tryExtractFromBroadPass(job.spec, merged);
+    if (extracted) {
+      broadPassResults.push({ entry: job.entry, spec: job.spec, ok: true, ...extracted });
+      extractedFromBroadPass++;
+    } else {
+      remainingJobs.push(job);
+    }
+  }
+
+  // One CLI call per unique dedup key; jobs sharing a key share the result.
+  const queryGroups = new Map();
+  for (const job of remainingJobs) {
+    const key = queryKey(job.spec, scope);
+    if (!queryGroups.has(key)) {
+      queryGroups.set(key, { spec: job.spec, jobs: [] });
+    }
+    queryGroups.get(key).jobs.push(job);
+  }
+  dedupedQueryHits = remainingJobs.length - queryGroups.size;
+
+  const totalCliQueries = queryGroups.size;
+  log(
+    `${flatJobs.length} specs total: ${extractedFromBroadPass} extracted from broad-pass, ${dedupedQueryHits} deduped, ${totalCliQueries} CLI queries to run`,
+  );
+
+  const groupResults = await Promise.all(
+    [...queryGroups.values()].map(async ({ spec, jobs }) => {
+      const r = await queryMetric(spec.metricId, {
+        aggregation: spec.aggregation,
+        groupBy: spec.groupBy,
+        filter: spec.filter,
+        since: spec.since,
+        limit: spec.limit,
+        scope,
+      });
+      return { spec, jobs, response: r };
+    }),
+  );
+
+  const cliResults = [];
+  for (const { spec, jobs, response: r } of groupResults) {
+    if (!r.ok) {
+      for (const job of jobs) {
+        errors.push({
+          candidateGroup: job.entry.group,
+          candidateIndex: job.entry.i,
+          kind: job.entry.c.kind,
+          route: job.entry.c.route ?? job.entry.c.hostname ?? null,
+          specId: spec.id,
+          code: r.code,
+        });
+        cliResults.push({ entry: job.entry, spec, ok: false, error: r.code });
+      }
+      continue;
+    }
+    const norm = normalizeResponse(r.data, spec);
+    for (const job of jobs) {
+      cliResults.push({ entry: job.entry, spec, ok: true, ...norm });
+    }
+  }
+  const results = [...broadPassResults, ...cliResults];
+
+  const wallMs = Date.now() - t0;
+  log(
+    `done in ${wallMs}ms (${totalCliQueries} CLI queries, ${extractedFromBroadPass} extracted from broad-pass, ${dedupedQueryHits} deduped, ${errors.length} errors)`,
+  );
+
+  const byCandidate = new Map();
+  for (const res of results) {
+    const k = `${res.entry.group}:${res.entry.i}`;
+    if (!byCandidate.has(k)) byCandidate.set(k, []);
+    byCandidate.get(k).push(res);
+  }
+
+  function enrich(c, group, i) {
+    const k = `${group}:${i}`;
+    const note = skipNotes.get(k);
+    if (note) {
+      return {
+        ...c,
+        evidence: {
+          ...(c.evidence ?? {}),
+          deepDive: { note },
+        },
+      };
+    }
+    const list = byCandidate.get(k) ?? [];
+    const merged = mergeIntoEvidence(list);
+    return {
+      ...c,
+      evidence: {
+        ...(c.evidence ?? {}),
+        deepDive: merged,
+      },
+    };
+  }
+
+  const enrichedToLaunch = toLaunch.map((c, i) => enrich(c, "toLaunch", i));
+  const enrichedPlatform = platform.map((c, i) => enrich(c, "platform", i));
+
+  const out = {
+    schemaVersion: SCHEMA_VERSION,
+    appliedAt: new Date().toISOString(),
+    candidatesEnriched: toLaunch.length + platform.length,
+    specsTotal: flatJobs.length,
+    queriesRun: totalCliQueries,
+    extractedFromBroadPass,
+    dedupedQueryHits,
+    totalWallMs: wallMs,
+    errors,
+    toLaunch: enrichedToLaunch,
+    platform: enrichedPlatform,
+  };
+
+  process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+}
+
+async function resolveDeepDiveCommandScope(merged, link) {
+  const linkedOrgId = merged.orgId ?? link.orgId ?? null;
+  if (merged.commandScope?.ok && (merged.commandScope.cliScope || !linkedOrgId)) {
+    return merged.commandScope;
+  }
+  if (merged.commandScope && merged.commandScope.ok === false) return merged.commandScope;
+
+  return await resolveCommandScope({
+    projectId: merged.projectId ?? link.projectId ?? null,
+    orgId: merged.orgId ?? link.orgId ?? null,
+  });
+}
+
+// Reduce CLI response to {value} or {rows:[{value,...dims}]}. The per-metric
+// underscore field (e.g. vercel_function_invocation_count_sum) gets renamed
+// to `value` for compactness.
+function normalizeResponse(data, spec) {
+  if (!data || !Array.isArray(data.summary)) return { value: null };
+  const field = `${spec.metricId.replace(/\./g, "_")}_${spec.aggregation}`;
+  if (spec.groupBy.length === 0) {
+    const first = data.summary[0];
+    if (!first) return { value: null };
+    const v = first[field];
+    return { value: typeof v === "number" ? round4(v) : null };
+  }
+  const rows = data.summary.map((row) => {
+    const out = { value: typeof row[field] === "number" ? round4(row[field]) : null };
+    for (const dim of spec.groupBy) {
+      if (row[dim] !== undefined) out[dim] = row[dim];
+    }
+    return out;
+  });
+  return { rows };
+}
+
+function round4(n) {
+  if (!Number.isFinite(n)) return n;
+  return Math.round(n * 10000) / 10000;
+}
+
+// Skip the CLI call when broad-pass already collected the same metric grouped
+// by [route, dim]. Returns {rows} on hit, null on miss. Cuts rate-limit pressure
+// for per-route slice specs (startTypeSplit, cacheBreakdown, methodDistribution).
+function tryExtractFromBroadPass(spec, merged) {
+  const eq = spec.broadPassEquivalent;
+  if (!eq) return null;
+  const broadRows = merged?.metrics?.[eq.key]?.rows;
+  if (!Array.isArray(broadRows)) return null;
+  const rows = [];
+  for (const row of broadRows) {
+    if (row.route !== eq.routeFilter) continue;
+    const out = { value: typeof row.value === "number" ? row.value : null };
+    for (const dim of eq.projectDims ?? []) {
+      if (row[dim] !== undefined) out[dim] = row[dim];
+    }
+    rows.push(out);
+  }
+  // Zero rows ≠ "no data" — broad-pass row limit may have truncated the route.
+  // Fall through to CLI so the caller gets a definitive answer.
+  if (rows.length === 0) return null;
+  return { rows };
+}
+
+// Two specs sharing this key answer the same question — one CLI call serves both.
+// Must include everything that affects the CLI's arg list.
+function queryKey(spec, scope) {
+  const groupBy = [...(spec.groupBy ?? [])].sort();
+  return JSON.stringify({
+    metricId: spec.metricId,
+    aggregation: spec.aggregation,
+    groupBy,
+    filter: spec.filter ?? null,
+    since: spec.since ?? null,
+    limit: spec.limit ?? null,
+    scope: scope ?? null,
+  });
+}
+
+main().catch((err) => {
+  console.error("[deep-dive] FAILED:", err.message);
+  console.error(err.stack);
+  process.exit(1);
+});