@oriro/orirocli 0.1.0

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

@@ -0,0 +1,371 @@
+// Per-candidate deep-dive query specs. Runs after gate, before sub-agent reads source.
+//
+// CLI quirks:
+//   - Multi `-a` flag is NOT supported. One percentile per query.
+//   - External-API "calling route" dim is `origin_route` (NOT `route`).
+
+// Same window as broad pass so rolls are comparable.
+import { TIME_WINDOW } from "./queries.mjs";
+
+export { TIME_WINDOW };
+
+// Per-query is scoped to one route/hostname, so cardinality stays small — higher than broad-pass caps.
+const DEPLOYMENT_LIMIT = 10;
+const ERROR_DEPLOYMENT_LIMIT = 30;
+const ERROR_CODE_LIMIT = 50;
+const WAF_RULE_LIMIT = 20;
+const MIDDLEWARE_PATH_LIMIT = 50;
+const CALLER_LIMIT = 20;
+
+// OData escapes a literal `'` inside a string by doubling it (`it's` → `it''s`).
+export function escapeODataString(s) {
+  if (typeof s !== "string") return "";
+  return s.replace(/'/g, "''");
+}
+
+export function odataEq(dim, value) {
+  return `${dim} eq '${escapeODataString(value)}'`;
+}
+
+export function odataAnd(...conds) {
+  return conds.filter(Boolean).join(" and ");
+}
+
+export const SPEC_GENERATORS = {
+  slow_route(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq("route", route);
+    // cacheBreakdown/bandwidthByCache let sub-agent see miss-path cost on static routes (dynamic='error' can still show p95=900ms over millions of requests).
+    return [
+      ...latencyPercentiles("latency", "vercel.function_invocation.function_duration_ms", f),
+      ...latencyPercentiles("ttfb", "vercel.function_invocation.ttfb_ms", f),
+      ...latencyPercentiles("cpu", "vercel.function_invocation.function_cpu_time_ms", f, ["p95"]),
+      {
+        id: "startTypeSplit",
+        metricId: "vercel.function_invocation.count",
+        aggregation: "sum",
+        groupBy: ["function_start_type"],
+        filter: f,
+        broadPassEquivalent: {
+          key: "fnStartTypeByRoute",
+          routeFilter: route,
+          projectDims: ["function_start_type"],
+        },
+      },
+      // function-invocation status (5xx from function) — distinct from request-level status, can't reuse broad-pass.
+      {
+        id: "statusDistribution",
+        metricId: "vercel.function_invocation.count",
+        aggregation: "sum",
+        groupBy: ["http_status"],
+        filter: f,
+      },
+      {
+        id: "perDeployment",
+        metricId: "vercel.function_invocation.function_duration_ms",
+        aggregation: "p95",
+        groupBy: ["deployment_id"],
+        filter: f,
+        limit: DEPLOYMENT_LIMIT,
+      },
+      {
+        id: "cacheBreakdown",
+        metricId: "vercel.request.count",
+        aggregation: "sum",
+        groupBy: ["cache_result"],
+        filter: f,
+        broadPassEquivalent: {
+          key: "requestsByRouteCache",
+          routeFilter: route,
+          projectDims: ["cache_result"],
+        },
+      },
+      // broad-pass bandwidthByCacheResult is account-wide, so per-route still required.
+      {
+        id: "bandwidthByCache",
+        metricId: "vercel.request.fdt_total_bytes",
+        aggregation: "sum",
+        groupBy: ["cache_result"],
+        filter: f,
+      },
+    ];
+  },
+
+  uncached_route(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq("route", route);
+    return [
+      {
+        id: "cacheBreakdown",
+        metricId: "vercel.request.count",
+        aggregation: "sum",
+        groupBy: ["cache_result"],
+        filter: f,
+        broadPassEquivalent: {
+          key: "requestsByRouteCache",
+          routeFilter: route,
+          projectDims: ["cache_result"],
+        },
+      },
+      {
+        id: "methodDistribution",
+        metricId: "vercel.request.count",
+        aggregation: "sum",
+        groupBy: ["request_method"],
+        filter: f,
+        broadPassEquivalent: {
+          key: "requestsByRouteMethod",
+          routeFilter: route,
+          projectDims: ["request_method"],
+        },
+      },
+      {
+        id: "botShare",
+        metricId: "vercel.request.fdt_total_bytes",
+        aggregation: "sum",
+        groupBy: ["bot_category"],
+        filter: f,
+      },
+      {
+        id: "bandwidthByCache",
+        metricId: "vercel.request.fdt_total_bytes",
+        aggregation: "sum",
+        groupBy: ["cache_result"],
+        filter: f,
+      },
+    ];
+  },
+
+  cold_start(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq("route", route);
+    return [
+      {
+        id: "startTypeSplit",
+        metricId: "vercel.function_invocation.count",
+        aggregation: "sum",
+        groupBy: ["function_start_type"],
+        filter: f,
+      },
+      {
+        id: "coldVsWarmLatencyP95",
+        metricId: "vercel.function_invocation.function_duration_ms",
+        aggregation: "p95",
+        groupBy: ["function_start_type"],
+        filter: f,
+      },
+      {
+        id: "coldByDeployment",
+        metricId: "vercel.function_invocation.count",
+        aggregation: "sum",
+        groupBy: ["deployment_id"],
+        filter: odataAnd(f, odataEq("function_start_type", "cold")),
+        limit: DEPLOYMENT_LIMIT,
+      },
+    ];
+  },
+
+  route_errors(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq("route", route);
+    return [
+      {
+        id: "errorStatusPattern",
+        metricId: "vercel.request.count",
+        aggregation: "sum",
+        groupBy: ["http_status"],
+        filter: odataAnd(f, "http_status ge '500'"),
+      },
+      {
+        id: "errorCodes",
+        metricId: "vercel.function_invocation.count",
+        aggregation: "sum",
+        groupBy: ["error_code"],
+        filter: f,
+        limit: ERROR_CODE_LIMIT,
+      },
+      {
+        id: "errorsByDeployment",
+        metricId: "vercel.function_invocation.count",
+        aggregation: "sum",
+        groupBy: ["deployment_id", "http_status"],
+        filter: f,
+        limit: ERROR_DEPLOYMENT_LIMIT,
+      },
+    ];
+  },
+
+  external_api_slow(c) {
+    const host = c.hostname;
+    if (!host) return [];
+    const f = odataEq("origin_hostname", host);
+    return [
+      ...latencyPercentiles("latency", "vercel.external_api_request.request_duration_ms", f),
+      {
+        // "calling route" dim is origin_route (verified via metrics schema).
+        id: "callersByRoute",
+        metricId: "vercel.external_api_request.count",
+        aggregation: "sum",
+        groupBy: ["origin_route"],
+        filter: f,
+        limit: CALLER_LIMIT,
+      },
+      {
+        id: "transferBytes",
+        metricId: "vercel.external_api_request.transfer_bytes",
+        aggregation: "sum",
+        groupBy: [],
+        filter: f,
+      },
+    ];
+  },
+
+  isr_overrevalidation(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq("route", route);
+    return [
+      {
+        id: "writePattern",
+        metricId: "vercel.isr_operation.write_units",
+        aggregation: "sum",
+        groupBy: ["cache_result"],
+        filter: f,
+      },
+      {
+        id: "readPattern",
+        metricId: "vercel.isr_operation.read_units",
+        aggregation: "sum",
+        groupBy: ["cache_result"],
+        filter: f,
+      },
+    ];
+  },
+
+  cwv_poor(c) {
+    const route = c.route;
+    if (!route) return [];
+    const f = odataEq("route", route);
+    return [
+      ...latencyPercentiles("lcp", "vercel.speed_insights_metric.lcp", f, ["p50", "p75", "p95"]),
+      ...latencyPercentiles("inp", "vercel.speed_insights_metric.inp", f, ["p50", "p75", "p95"]),
+      ...latencyPercentiles("cls", "vercel.speed_insights_metric.cls", f, ["p50", "p75", "p95"]),
+    ];
+  },
+
+  middleware_heavy(_c) {
+    // Account-scope. Surface top middleware-paths so recommender has named targets.
+    return [
+      {
+        id: "topMiddlewarePaths",
+        metricId: "vercel.middleware_invocation.count",
+        aggregation: "sum",
+        groupBy: ["request_path"],
+        limit: MIDDLEWARE_PATH_LIMIT,
+      },
+    ];
+  },
+
+  platform_fluid_compute(_c) {
+    // Broad-pass fnStartTypeByRoute already covers this account-scope rec; runner notes reuse.
+    return [];
+  },
+
+  platform_bot_protection(_c) {
+    return [
+      {
+        id: "wafRuleFirings",
+        metricId: "vercel.firewall_action.count",
+        aggregation: "sum",
+        groupBy: ["waf_rule_id"],
+        limit: WAF_RULE_LIMIT,
+      },
+    ];
+  },
+
+  observability_events_attribution(_c) {
+    // Account-scope billing signal; broad-pass usage and existing route/cache/middleware metrics carry the evidence.
+    return [];
+  },
+
+  usage_spike_triage(_c) {
+    // Daily billing breakdown is already in the gate evidence; no per-candidate metrics query exists.
+    return [];
+  },
+
+  build_minutes_fanout(_c) {
+    // Account-scope billing signal + scanner findings carry the evidence; no per-candidate query.
+    return [];
+  },
+
+  region_misconfig(_c) {
+    // Branch 2 (scanner-only) — per-region TTFB metric unavailable today, so no deep-dive query.
+    return [];
+  },
+};
+
+// Scanner-driven kinds skip deep-dive — evidence already in scanner findings (file + line).
+export const SCANNER_KINDS = new Set([
+  "image_optimization",
+  "cache_header_gap",
+  "rendering_candidate",
+  "use_cache_date_stamp",
+  "cache_components_suspense_dedupe",
+]);
+
+export function specsForCandidate(candidate) {
+  const kind = candidate?.kind;
+  if (!kind) return [];
+  if (SCANNER_KINDS.has(kind)) return [];
+  const gen = SPEC_GENERATORS[kind];
+  if (!gen) return [];
+  return gen(candidate).map((s) => ({ since: TIME_WINDOW, ...s }));
+}
+
+// One spec per percentile — CLI does not support `-a p50 -a p95` multi-aggregation.
+function latencyPercentiles(
+  idPrefix,
+  metricId,
+  filter,
+  percentiles = ["p50", "p75", "p95", "p99"],
+) {
+  return percentiles.map((p) => ({
+    id: `${idPrefix}.${p}`,
+    metricId,
+    aggregation: p,
+    groupBy: [],
+    filter,
+  }));
+}
+
+// Dot-notation spec ids (`latency.p95`) nest under their group prefix.
+export function mergeIntoEvidence(results) {
+  const out = {};
+  for (const r of results) {
+    const id = r?.spec?.id;
+    if (!id) continue;
+    const dot = id.indexOf(".");
+    if (dot > -1) {
+      const head = id.slice(0, dot);
+      const leaf = id.slice(dot + 1);
+      if (!out[head]) out[head] = {};
+      out[head][leaf] = simplify(r);
+    } else {
+      out[id] = simplify(r);
+    }
+  }
+  return out;
+}
+
+// Avoid leaking raw CLI payload / candidate+spec wrapper into evidence — keep summary-only.
+function simplify(r) {
+  if (!r || r.ok === false) return { error: r?.error ?? "unknown" };
+  // Check rows before value so tabular results with both stay tabular.
+  if (Array.isArray(r.rows)) return r.rows;
+  if ("value" in r) return r.value;
+  return null;
+}

package/skills/craft/vercel-optimize/lib/display-labels.mjs

@@ -0,0 +1,219 @@
+import { canonicalizeRoute } from "./route-normalize.mjs";
+
+const KIND_LABELS = new Map([
+  ["slow_route", "Slow route"],
+  ["uncached_route", "Low cache-hit route"],
+  ["cold_start", "Cold starts"],
+  ["route_errors", "Route errors"],
+  ["cache_header_gap", "Missing cache headers"],
+  ["image_optimization", "Image optimization"],
+  ["external_api_slow", "Slow external API"],
+  ["isr_overrevalidation", "ISR over-revalidation"],
+  ["middleware_heavy", "Heavy middleware"],
+  ["cwv_poor", "Poor Core Web Vitals"],
+  ["platform_fluid_compute", "Fluid Compute usage"],
+  ["platform_bot_protection", "Bot traffic"],
+  ["rendering_candidate", "Rendering opportunity"],
+  ["missing_cache_headers", "Missing cache headers"],
+  ["max_age_without_s_maxage", "Browser-only cache header"],
+  ["force_dynamic", "Forced dynamic rendering"],
+  ["headers_in_page", "Dynamic API in page"],
+  ["unoptimized_image", "Image optimization gap"],
+  ["large_static_asset", "Large static asset"],
+  ["source_maps_production", "Production source maps"],
+  ["edge_heavy_import", "Heavy Edge import"],
+]);
+
+const SIGNAL_LABELS = new Map([
+  ["inv", "function invocations"],
+  ["runs", "function invocations"],
+  ["middleware_inv", "middleware invocations"],
+  ["total_req", "total requests"],
+  ["requests", "requests"],
+  ["p95", "95th percentile duration"],
+  ["p75", "75th percentile duration"],
+  ["5xx", "5xx error rate"],
+  ["errs", "5xx errors"],
+  ["rate", "5xx error rate"],
+  ["cache", "cache hit rate"],
+  ["get", "GET request share"],
+  ["cold", "cold start rate"],
+  ["writes", "ISR write units"],
+  ["reads", "ISR read units"],
+  ["w/r", "ISR writes per read"],
+  ["ratio", "ratio"],
+  ["host", "host"],
+  ["calls", "external API calls"],
+  ["edge_cost", "Edge Request cost units"],
+  ["bot_protection", "Bot Protection"],
+  ["bot_fdt_pct", "bot Fast Data Transfer share"],
+  ["LCP", "Largest Contentful Paint (LCP)"],
+  ["INP", "Interaction to Next Paint (INP)"],
+  ["CLS", "Cumulative Layout Shift (CLS)"],
+]);
+
+const REQUEST_COUNT_KINDS = new Set(["uncached_route"]);
+
+const PUBLIC_ASSIGNMENT_LABELS = new Map([
+  ...SIGNAL_LABELS,
+  ["deepDive.latency.p95", "deepDive latency p95"],
+  ["deepDive.cpu.p95", "deepDive CPU p95"],
+  ["deepDive.ttfb.p95", "deepDive TTFB p95"],
+  ["cpu.p95", "CPU p95"],
+  ["latency.p95", "latency p95"],
+  ["ttfb.p95", "TTFB p95"],
+  ["cache_result", "cache result"],
+  ["http_status", "HTTP status"],
+  ["error_code", "error code"],
+  ["status", "status"],
+  ["count", "count"],
+]);
+
+export function formatKind(kind) {
+  if (!kind) return "Candidate";
+  if (KIND_LABELS.has(kind)) return KIND_LABELS.get(kind);
+  return (
+    String(kind)
+      .split(/[_-]+/g)
+      .filter(Boolean)
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+      .join(" ") || "Candidate"
+  );
+}
+
+export function formatRoute(candidate) {
+  const route = candidate?.displayRoute ?? candidate?.route ?? candidate?.hostname ?? null;
+  if (route) return String(canonicalizeRoute(route));
+  if (Array.isArray(candidate?.files) && candidate.files.length > 0) return candidate.files[0];
+  return "account-wide";
+}
+
+export function formatSignal(signal, context = {}) {
+  if (typeof signal !== "string" || signal.trim() === "") return "no signal recorded";
+
+  const parts = signal
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => formatSignalPart(part, context));
+
+  return parts.length > 0 ? parts.join("; ") : signal;
+}
+
+export function formatPublicText(value) {
+  if (value == null) return "";
+  return normalizeObservedWindowUnits(String(value))
+    .replace(/\bo11y\b/gi, "observability")
+    .replace(/\bcache[- ]components gotcha\b/gi, "Cache Components edge case")
+    .replace(/\bcache_result\b(?!\s*=)/g, "cache result")
+    .replace(/\bhttp_status\b(?!\s*=)/g, "HTTP status")
+    .replace(/\berror_code\b(?!\s*=)/g, "error code")
+    .replace(/,(?=\s*([A-Za-z0-9][\w./-]*)=)/g, (match, key) =>
+      PUBLIC_ASSIGNMENT_LABELS.has(key) ? "; " : match,
+    )
+    .replace(/\b([A-Za-z0-9][\w./-]*)=([^,;\s]+)/g, (match, key, rawValue) => {
+      const label = PUBLIC_ASSIGNMENT_LABELS.get(key);
+      if (!label) return match;
+      return `${label}: ${formatSignalValue(key, rawValue)}`;
+    })
+    .replace(
+      /\b(cache breakdown[^.!?\n;]{0,160}?)\b(?:function\s+)?invocations\b/gi,
+      (match, prefix) => (/\bstatus distribution\b/i.test(prefix) ? match : `${prefix}requests`),
+    )
+    .replace(
+      /\b(cache breakdown[^.!?\n;]{0,220}?\bout of\s+[\d,]+)\s+invocations\b/gi,
+      "$1 requests",
+    )
+    .replace(/\b(cache hits over\s+[\d,.]+(?:\s?(?:K|M|B))?)\s+invocations\b/gi, "$1 requests")
+    .replace(
+      /\b(?:function\s+)?invocations\b([^.!?\n;]{0,120}\b(?:empty\s+)?cache result(?: label)?\b)/gi,
+      "requests$1",
+    );
+}
+
+export function normalizeObservedWindowUnits(value) {
+  if (value == null) return "";
+  return String(value)
+    .replace(/(?<!\$)\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/mo\b/gi, "$1/window")
+    .replace(/\bmonthly\s+function\s+invocations\b/gi, "function invocations/window")
+    .replace(
+      /\b(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\/mo\b/gi,
+      "$1/window",
+    )
+    .replace(
+      /\bmonthly\s+(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\b/gi,
+      "$1/window",
+    )
+    .replace(
+      /\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+function\s+invocations\s+per month\b/gi,
+      "$1 function invocations/window",
+    )
+    .replace(
+      /\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+(requests?|GETs|invocations?|bytes|writes?|reads?|errors?)\s+per month\b/gi,
+      "$1 $2/window",
+    )
+    .replace(
+      /\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/window\s+(requests?|GETs|(?:function\s+)?invocations?|bytes|egress|bandwidth|writes?|reads?|errors?)\b/gi,
+      "$1 $2 in this window",
+    )
+    .replace(
+      /\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\s+(requests?|GETs|(?:function\s+)?invocations?|bytes|egress|bandwidth|writes?|reads?|errors?)\/window\b/gi,
+      "$1 $2 in this window",
+    )
+    .replace(/\b(\d[\d,.]*(?:\s?(?:K|M|B|KB|MB|GB|TB))?)\/window\b/gi, "$1 in this window")
+    .replace(
+      /\b(requests?|invocations?|GETs|bytes|egress|bandwidth|writes?|reads?|errors?)\/window\b/gi,
+      "$1 in this window",
+    );
+}
+
+export function formatCandidateLine(candidate) {
+  return `${formatKind(candidate?.kind)} on ${formatRoute(candidate)} - ${formatSignal(candidate?.o11ySignal, candidate)}`;
+}
+
+export function formatCandidateLabel(candidate) {
+  return `${formatKind(candidate?.kind)} on ${formatRoute(candidate)}`;
+}
+
+function formatSignalPart(part, context = {}) {
+  const eq = part.indexOf("=");
+  if (eq === -1) return part;
+
+  const key = part.slice(0, eq).trim();
+  const value = part.slice(eq + 1).trim();
+  const label = signalLabel(key, context);
+  return `${label}: ${formatSignalValue(key, value)}`;
+}
+
+function signalLabel(key, context = {}) {
+  const kind = typeof context === "string" ? context : context?.kind;
+  if (key === "inv" && REQUEST_COUNT_KINDS.has(kind)) return "requests";
+  return SIGNAL_LABELS.get(key) ?? humanizeKey(key);
+}
+
+function humanizeKey(key) {
+  return String(key).replaceAll(".", " ").replaceAll("_", " ").replaceAll("-", " ").trim();
+}
+
+function formatSignalValue(key, value) {
+  if (
+    key === "inv" ||
+    key === "runs" ||
+    key === "middleware_inv" ||
+    key === "total_req" ||
+    key === "requests" ||
+    key === "calls" ||
+    key === "errs" ||
+    key === "writes" ||
+    key === "reads"
+  ) {
+    return formatNumberLike(value);
+  }
+  return value;
+}
+
+function formatNumberLike(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return value;
+  return new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(n);
+}