adevkit 0.1.0__py3-none-any.whl

devkit/skills/embedded/vercel-optimize/lib/vercel.mjs

@@ -0,0 +1,864 @@
+// Vercel CLI helpers. All shell-outs use execFile (not exec) — no shell injection. Error detection: exit code + JSON-parse first; stderr grep only as fallback (CLI error strings aren't a stable contract).
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, access } from 'node:fs/promises';
+import { join, win32 } from 'node:path';
+import { getMetricThrottle, isDailyQuotaExceeded, retryOnRateLimit } from './throttle.mjs';
+
+const exec = promisify(execFile);
+
+// On Windows, execFile cannot run the `vercel.cmd` shim directly: PATHEXT is not
+// applied by execFile, and .cmd/.bat require `shell: true` since Node 20 — but a
+// shell would mangle args containing spaces or URL query strings (e.g.
+// `vercel api '/v9/projects/:id?teamId=:org'`, `-f 'http_status ge 500'`). So we
+// resolve the Vercel package's JS entry from PATH and run it via `node` directly:
+// no shell, every arg passed verbatim. POSIX is unchanged (`vercel` on PATH).
+export function resolveVercelCommand({
+  platform = process.platform,
+  env = process.env,
+  execPath = process.execPath,
+  exists = existsSync,
+  readText = (file) => readFileSync(file, 'utf-8'),
+} = {}) {
+  if (platform !== 'win32') return { file: 'vercel', prefix: [] };
+
+  const pathValue = env.PATH || env.Path || env.path || '';
+  for (const dir of pathValue.split(win32.delimiter).filter(Boolean)) {
+    const entry = resolveVercelPackageEntry(dir, exists);
+    if (entry) return { file: execPath, prefix: [entry] };
+
+    const shimEntry = resolveVercelShimEntry(dir, exists, readText);
+    if (shimEntry) return { file: execPath, prefix: [shimEntry] };
+  }
+
+  return { file: execPath, prefix: [], missing: true };
+}
+
+function resolveVercelPackageEntry(dir, exists) {
+  const packageRoots = [
+    win32.join(dir, 'node_modules', 'vercel'),
+    win32.join(win32.dirname(dir), 'vercel'),
+  ];
+  for (const root of packageRoots) {
+    for (const rel of ['dist/vc.js', 'dist/index.js']) {
+      const entry = win32.join(root, rel);
+      if (exists(entry)) return entry;
+    }
+  }
+  return null;
+}
+
+function resolveVercelShimEntry(dir, exists, readText) {
+  for (const bin of ['vercel.cmd', 'vc.cmd']) {
+    const shim = win32.join(dir, bin);
+    if (!exists(shim)) continue;
+    let raw;
+    try {
+      raw = readText(shim);
+    } catch {
+      continue;
+    }
+    const match = raw.match(/["']([^"'\r\n]*vercel[\\/]+dist[\\/]+(?:vc|index)\.js)["']/i);
+    if (!match) continue;
+    const entry = normalizeWindowsShimTarget(match[1], dir);
+    if (exists(entry)) return entry;
+  }
+  return null;
+}
+
+function normalizeWindowsShimTarget(target, dir) {
+  const baseDir = `${dir}${win32.sep}`;
+  const expanded = target
+    .replace(/%~dp0/gi, baseDir)
+    .replace(/%dp0%/gi, baseDir)
+    .replace(/\$basedir/g, dir);
+  return win32.normalize(win32.isAbsolute(expanded) ? expanded : win32.resolve(dir, expanded));
+}
+
+async function runVercel(args, opts = {}) {
+  const command = resolveVercelCommand({ env: opts.env });
+  if (command.missing) {
+    const err = new Error('VERCEL_NOT_INSTALLED: `vercel` CLI not found in PATH. Install with `npm i -g vercel@latest`.');
+    err.code = 'ENOENT';
+    throw err;
+  }
+  return await exec(command.file, [...command.prefix, ...args], { windowsHide: true, ...opts });
+}
+
+const MIN_CLI_VERSION = [53, 0, 0];
+
+// Pre-v53 lacks `vercel metrics` and `vercel contract`.
+export async function checkCliVersion() {
+  let raw;
+  try {
+    const { stdout } = await runVercel(['--version']);
+    raw = stdout.trim();
+  } catch (err) {
+    throw new Error('VERCEL_NOT_INSTALLED: `vercel` CLI not found in PATH. Install with `npm i -g vercel@latest`.');
+  }
+  const m = raw.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!m) throw new Error(`VERCEL_VERSION_UNPARSEABLE: ${raw}`);
+  const v = [Number(m[1]), Number(m[2]), Number(m[3])];
+  for (let i = 0; i < 3; i++) {
+    if (v[i] > MIN_CLI_VERSION[i]) return v;
+    if (v[i] < MIN_CLI_VERSION[i]) {
+      throw new Error(
+        `VERCEL_CLI_TOO_OLD: have ${v.join('.')}, need >= ${MIN_CLI_VERSION.join('.')}. Upgrade with \`npm i -g vercel@latest\`.`
+      );
+    }
+  }
+  return v;
+}
+
+export async function checkAuth() {
+  try {
+    await runVercel(['whoami']);
+  } catch {
+    throw new Error('NOT_AUTH: run `vercel login`.');
+  }
+}
+
+export async function getCliIdentity() {
+  const r = await runVercelJson(['whoami', '--format', 'json']);
+  return r.ok ? r.data : null;
+}
+
+// Supports newer `.vercel/repo.json` (multi-project) + legacy `.vercel/project.json` (single-project).
+export async function readProjectJson(cwd = process.cwd()) {
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'repo.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    const projects = Array.isArray(parsed?.projects) ? parsed.projects.filter((p) => p?.id) : [];
+    if (projects.length > 1) {
+      throw new Error('AMBIGUOUS_PROJECT_LINK: `.vercel/repo.json` contains multiple projects. Run from the linked app directory, or pass the intended projectId together with VERCEL_ORG_ID.');
+    }
+    const first = projects[0];
+    if (first?.id) {
+      return { projectId: first.id, orgId: first.orgId ?? null, source: 'repo.json' };
+    }
+  } catch (err) {
+    if (err?.message?.startsWith('AMBIGUOUS_PROJECT_LINK:')) throw err;
+    /* fall through */
+  }
+
+  // Legacy single-project format.
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'project.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed?.projectId) {
+      return { projectId: parsed.projectId, orgId: parsed.orgId ?? null, source: 'project.json' };
+    }
+  } catch { /* fall through */ }
+
+  return null;
+}
+
+// Does NOT auto-run `vercel link` — interactive surprises bad.
+export async function resolveProjectId(explicit, cwd = process.cwd()) {
+  if (explicit) {
+    const linked = process.env.VERCEL_ORG_ID
+      ? null
+      : await readLinkedOwnerForProjectId(explicit, cwd);
+    return {
+      projectId: explicit,
+      orgId: process.env.VERCEL_ORG_ID || linked?.orgId || null,
+      source: linked?.source ? `arg+${linked.source}` : 'arg',
+    };
+  }
+  if (process.env.VERCEL_PROJECT_ID) {
+    const linked = process.env.VERCEL_ORG_ID
+      ? null
+      : await readLinkedOwnerForProjectId(process.env.VERCEL_PROJECT_ID, cwd);
+    return {
+      projectId: process.env.VERCEL_PROJECT_ID,
+      orgId: process.env.VERCEL_ORG_ID || linked?.orgId || null,
+      source: linked?.source ? `env+${linked.source}` : 'env',
+    };
+  }
+  return await readProjectJson(cwd);
+}
+
+async function readLinkedOwnerForProjectId(projectId, cwd = process.cwd()) {
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'repo.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    const matches = (Array.isArray(parsed?.projects) ? parsed.projects : [])
+      .filter((p) => p?.id && String(p.id) === String(projectId));
+    if (matches.length > 1) {
+      throw new Error('AMBIGUOUS_PROJECT_LINK: `.vercel/repo.json` contains multiple entries for the requested projectId. Ask the user to confirm the intended Vercel team/personal scope.');
+    }
+    const match = matches[0];
+    if (match?.orgId) return { orgId: match.orgId, source: 'repo.json' };
+  } catch (err) {
+    if (err?.message?.startsWith('AMBIGUOUS_PROJECT_LINK:')) throw err;
+    /* fall through */
+  }
+
+  try {
+    const raw = await readFile(join(cwd, '.vercel', 'project.json'), 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (String(parsed?.projectId ?? '') === String(projectId) && parsed?.orgId) {
+      return { orgId: parsed.orgId, source: 'project.json' };
+    }
+  } catch { /* fall through */ }
+
+  return null;
+}
+
+export async function resolveCommandScope(project = {}) {
+  const orgId = project?.orgId ?? null;
+
+  if (!orgId) {
+    return {
+      ok: false,
+      cliScope: null,
+      source: 'missing-org-scope',
+      required: true,
+      error: 'PROJECT_SCOPE_UNRESOLVED',
+      detail: 'The project was resolved without an owner account, so the collector cannot prove which Vercel scope to query.',
+    };
+  }
+
+  const identity = await getCliIdentity();
+  const currentTeam = identity?.team ?? null;
+
+  if (String(orgId).startsWith('team_')) {
+    if (currentTeam?.id === orgId && currentTeam?.slug) {
+      return {
+        ok: true,
+        cliScope: currentTeam.slug,
+        source: 'whoami-current-team',
+        required: true,
+        teamId: orgId,
+        detail: 'Resolved linked team ID to the current CLI team slug.',
+      };
+    }
+
+    const team = await getTeamInfo(orgId);
+    if (team.ok && team.slug) {
+      return {
+        ok: true,
+        cliScope: team.slug,
+        source: 'team-api',
+        required: true,
+        teamId: orgId,
+        detail: 'Resolved linked team ID to a Vercel CLI scope slug.',
+      };
+    }
+
+    return {
+      ok: false,
+      cliScope: null,
+      source: 'team-api',
+      required: true,
+      teamId: orgId,
+      error: team.error ?? 'TEAM_SCOPE_UNRESOLVED',
+      detail: 'Could not resolve the linked team ID to a Vercel CLI scope slug.',
+    };
+  }
+
+  if (String(orgId).startsWith('usr_')) {
+    const user = identity?.user ?? identity ?? {};
+    const userId = user.id ?? identity?.id ?? null;
+    const username = user.username ?? identity?.username ?? null;
+    if ((!userId || userId === orgId) && username) {
+      return {
+        ok: true,
+        cliScope: username,
+        source: 'whoami-user',
+        required: true,
+        userId: orgId,
+        detail: 'Resolved linked user ID to a Vercel CLI username scope.',
+      };
+    }
+    return {
+      ok: false,
+      cliScope: null,
+      source: 'whoami-user',
+      required: true,
+      userId: orgId,
+      error: 'USER_SCOPE_UNRESOLVED',
+      detail: 'Could not resolve the linked user ID to the authenticated Vercel username.',
+    };
+  }
+
+  return {
+    ok: true,
+    cliScope: orgId,
+    source: 'linked-org-scope',
+    required: true,
+    detail: 'Using the linked org value as the Vercel CLI scope.',
+  };
+}
+
+async function getTeamInfo(teamIdOrSlug) {
+  const r = await runVercelJson(['api', `/v2/teams/${encodeURIComponent(teamIdOrSlug)}`]);
+  if (!r.ok) return { ok: false, error: r.code ?? 'UNKNOWN' };
+  const team = r.data?.team ?? r.data ?? {};
+  return {
+    ok: true,
+    id: team.id ?? null,
+    slug: team.slug ?? null,
+    name: team.name ?? null,
+  };
+}
+
+// Some commands emit `{error: {...}}` on stdout AND exit non-zero — parse stdout first; embedded `error` is the most reliable signal.
+// 32 MiB buffer: 14d function-duration timeseries across many routes exceeds Node's 1 MiB default.
+export async function runVercelJson(args, opts = {}) {
+  let stdout = '';
+  let stderr = '';
+  let exitCode = 0;
+  try {
+    const r = await runVercel(args, { maxBuffer: 32 * 1024 * 1024, ...opts });
+    stdout = r.stdout;
+    stderr = r.stderr;
+  } catch (err) {
+    stdout = err.stdout || '';
+    stderr = err.stderr || '';
+    exitCode = err.code ?? err.exitCode ?? 1;
+  }
+  const safeStderr = redactSensitiveText(stderr);
+
+  if (stdout && stdout.trim().startsWith('{')) {
+    try {
+      const data = JSON.parse(stdout);
+      if (data && typeof data === 'object' && data.error) {
+        const failure = {
+          ok: false,
+          code: data.error.code || `EXIT_${exitCode}`,
+          message: redactSensitiveText(data.error.message || ''),
+          allowedValues: data.error.allowedValues,
+          stderr: safeStderr,
+        };
+        return isDailyQuotaExceeded(failure)
+          ? { ...failure, code: 'DAILY_QUOTA_EXCEEDED', originalCode: failure.code }
+          : failure;
+      }
+      if (exitCode === 0) return { ok: true, data };
+      // Exit non-zero, no `error` key, parseable stdout → still useful.
+      return { ok: true, data };
+    } catch {
+      /* fall through to stderr categorization */
+    }
+  }
+
+  // Metrics schema returns a top-level array.
+  if (stdout && stdout.trim().startsWith('[')) {
+    try {
+      const data = JSON.parse(stdout);
+      if (exitCode === 0) return { ok: true, data };
+    } catch { /* fall through */ }
+  }
+
+  return {
+    ok: false,
+    code: categorizeError(exitCode, stderr),
+    stderr: safeStderr,
+  };
+}
+
+export function redactSensitiveText(value) {
+  return String(value ?? '')
+    .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/=-]{12,}/gi, '$1 [REDACTED]')
+    .replace(/\b(Authorization:\s*)[^\r\n]+/gi, '$1[REDACTED]')
+    .replace(/\b(x-vercel-id:\s*)[^\r\n]+/gi, '$1[REDACTED]')
+    .replace(/\b(VERCEL_TOKEN|TURBO_TOKEN|NPM_TOKEN|NODE_AUTH_TOKEN|GITHUB_TOKEN)=("[^"]+"|'[^']+'|[^\s"'`]+)/g, '$1=[REDACTED]')
+    .replace(/(--token(?:=|\s+))("[^"]+"|'[^']+'|[^\s"'`]+)/gi, '$1[REDACTED]')
+    .replace(/\b(prj|team|usr)_[A-Za-z0-9]{8,}\b/g, '$1_[REDACTED]')
+    .replace(/("token"\s*:\s*")[^"]{8,}(")/gi, '$1[REDACTED]$2');
+}
+
+// CLI doesn't emit machine-readable error codes for these states — stderr substring is fallback only.
+function categorizeError(exitCode, stderr) {
+  const lc = (stderr || '').toLowerCase();
+  if (isDailyQuotaExceeded({ ok: false, stderr })) return 'DAILY_QUOTA_EXCEEDED';
+  if (lc.includes('observability plus')) return 'OPLUS_REQUIRED';
+  if (lc.includes('costs not found')) return 'USAGE_UNAVAILABLE';
+  if (lc.includes('project not found')) return 'PROJECT_NOT_FOUND';
+  if (lc.includes('not linked') || lc.includes('no project')) return 'NOT_LINKED';
+  if (lc.includes('log in') || lc.includes('credentials')) return 'NOT_AUTH';
+  if (lc.includes('rate limit') || lc.includes('429')) return 'RATE_LIMIT';
+  if (lc.includes('permission') || lc.includes('not authorized') || lc.includes('403'))
+    return 'FORBIDDEN';
+  return `EXIT_${exitCode}`;
+}
+
+// Schema is global per team — pass scope so we hit the right team rather than user's currentTeam.
+export async function hasObservabilityPlus(scope) {
+  const r = await runVercelJson(scopedArgs(['metrics', 'schema', '--format', 'json'], scope));
+  return r.ok;
+}
+
+export async function getMetricsSchema(scope) {
+  const r = await runVercelJson(scopedArgs(['metrics', 'schema', '--format', 'json'], scope));
+  return r.ok ? r.data : null;
+}
+
+export async function checkObservabilityPlusConfiguration({ orgId, projectId } = {}) {
+  if (!orgId) {
+    return {
+      ok: false,
+      source: 'observability-configuration-api',
+      blocker: 'unknown',
+      detail: 'No team ID was available for the Observability Plus configuration preflight.',
+    };
+  }
+  if (String(orgId).startsWith('usr_')) {
+    return {
+      ok: false,
+      source: 'observability-configuration-api',
+      access: null,
+      blocker: 'unknown',
+      detail: 'The Observability Plus team configuration preflight is not available for a user-owned project; falling back to the scoped metrics probe.',
+    };
+  }
+  const qs = `?teamId=${encodeURIComponent(orgId)}`;
+  const r = await runVercelJson(['api', `/v1/observability/manage/configuration/projects${qs}`]);
+  return classifyObservabilityPlusConfiguration(r, { projectId });
+}
+
+export function classifyObservabilityPlusConfiguration(result, { projectId } = {}) {
+  const source = 'observability-configuration-api';
+  if (result?.ok) {
+    const disabledProjects = Array.isArray(result.data?.disabledProjects) ? result.data.disabledProjects : [];
+    const disabled = projectId
+      ? disabledProjects.find((p) => String(p?.id ?? '') === String(projectId))
+      : null;
+    if (disabled) {
+      return {
+        ok: true,
+        source,
+        access: false,
+        blocker: 'project_disabled',
+        detail: 'Observability Plus is enabled for the team but disabled for this project.',
+        disabledProject: {
+          id: disabled.id,
+          name: disabled.name ?? null,
+          disabledAt: disabled.disabledAt ?? null,
+        },
+      };
+    }
+    return {
+      ok: true,
+      source,
+      access: true,
+      blocker: null,
+      detail: 'Observability Plus is enabled for this team/project.',
+    };
+  }
+
+  const code = String(result?.code ?? 'unknown').toLowerCase();
+  const text = `${result?.message ?? ''}\n${result?.stderr ?? ''}`.toLowerCase();
+  const mentionsObservabilityPlusNotEnabled =
+    /observability plus[\s\S]{0,160}not enabled/.test(text) ||
+    /not enabled[\s\S]{0,160}observability plus/.test(text) ||
+    /subscription to observability plus[\s\S]{0,160}required/.test(text);
+  if (code === 'oplus_required' || ((code === 'not_found' || code === '404') && mentionsObservabilityPlusNotEnabled)) {
+    return {
+      ok: true,
+      source,
+      access: false,
+      blocker: 'no_oplus_probe',
+      detail: 'Route-level metrics are unavailable because Observability Plus is not enabled for this team.',
+    };
+  }
+  if (/forbidden|not_authorized|403/.test(code) || /forbidden|not authorized|permission|403/.test(text)) {
+    return {
+      ok: false,
+      source,
+      access: null,
+      blocker: 'forbidden',
+      detail: 'Could not read Observability Plus configuration for this team. Run `vercel switch <team>` and verify access.',
+    };
+  }
+  if (/not_auth|unauthorized|401/.test(code) || /unauthorized|log in|credentials|401/.test(text)) {
+    return {
+      ok: false,
+      source,
+      access: null,
+      blocker: 'forbidden',
+      detail: 'Could not read Observability Plus configuration because the Vercel CLI is not authenticated.',
+    };
+  }
+  return {
+    ok: false,
+    source,
+    access: null,
+    blocker: 'unknown',
+    detail: `Could not determine Observability Plus configuration before querying metrics (code=${code}).`,
+  };
+}
+
+// Returns `{ok, ...}`. CLI summary defaults to top 10 groups under --group-by; widen via opts.limit.
+export async function queryMetric(metricId, opts = {}) {
+  const args = ['metrics', metricId, '--format', 'json'];
+  if (opts.aggregation) args.push('-a', opts.aggregation);
+  for (const dim of opts.groupBy ?? []) args.push('--group-by', dim);
+  if (opts.filter) args.push('-f', opts.filter);
+  if (opts.since) args.push('--since', opts.since);
+  if (opts.until) args.push('--until', opts.until);
+  if (opts.limit) args.push('--limit', String(opts.limit));
+
+  // 3-layer protection: semaphore (8 concurrent) + sliding-window (80/60s) + retryOnRateLimit (3× 60-90s jitter). payment_required is terminal.
+  const throttle = getMetricThrottle();
+  const onRetry = (attempt, delayMs) => {
+    console.error(`[queryMetric] ${metricId} hit RATE_LIMITED; retry ${attempt}/3 after ${(delayMs / 1000).toFixed(0)}s`);
+  };
+  return await throttle.run(() =>
+    retryOnRateLimit(() => runVercelJson(scopedArgs(args, opts.scope)), { onRetry })
+  );
+}
+
+// Team-owned projects need `?teamId=<orgId>` to avoid current-team drift. User-
+// owned projects use the authenticated user context and should not pass teamId.
+export async function getProjectConfig(projectId, orgId) {
+  const qs = orgId && !String(orgId).startsWith('usr_')
+    ? `?teamId=${encodeURIComponent(orgId)}`
+    : '';
+  const r = await runVercelJson(['api', `/v9/projects/${projectId}${qs}`]);
+  return r.ok ? r.data : { error: r.code, stderr: r.stderr };
+}
+
+// USAGE_UNAVAILABLE distinguishes "no Costs feature" from genuine emptiness.
+export async function getUsage({ days = 14, scope, groupByProject = true } = {}) {
+  const toDate = new Date();
+  const fromDate = new Date(toDate.getTime() - days * 86400000);
+  const fmt = (d) => d.toISOString().slice(0, 10);
+  const args = [
+    'usage',
+    '--format', 'json',
+    '--from', fmt(fromDate),
+    '--to', fmt(toDate),
+  ];
+  // The CLI rejects --breakdown with --group-by. Project grouping is higher
+  // value for this skill because every recommendation must be project-scoped.
+  if (groupByProject) args.push('--group-by', 'project');
+  else args.push('--breakdown', 'daily');
+  return await runVercelJson(scopedArgs(args, scope));
+}
+
+// CLI `--group-by project` returns project buckets under groupBy.data. Older
+// breakdown-shaped fixtures tag service rows with projectId; keep both paths.
+export function filterUsageByProject(usage, projectId, projectName = null) {
+  if (!usage || !projectId) return { filtered: null, matched: false, unattributedTotal: 0 };
+  if (usage.groupBy?.dimension === 'project' && Array.isArray(usage.groupBy.data)) {
+    const project = usage.groupBy.data.find((entry) => projectMatches(entry, projectId, projectName));
+    if (!project) return { filtered: null, matched: false, unattributedTotal: 0 };
+    return {
+      filtered: {
+        ...usage,
+        groupBy: { ...usage.groupBy, data: [project] },
+        services: Array.isArray(project.services) ? project.services : [],
+        totals: project.totals ?? null,
+        project: { name: project.name ?? projectName ?? null, projectId: project.projectId ?? projectId },
+      },
+      matched: true,
+      unattributedTotal: 0,
+    };
+  }
+  const breakdown = usage.breakdown;
+  if (!breakdown || !Array.isArray(breakdown.data)) {
+    return { filtered: null, matched: false, unattributedTotal: 0 };
+  }
+  const out = {
+    ...usage,
+    breakdown: { ...breakdown, data: [] },
+  };
+  let matchedAny = false;
+  let projectTotal = 0;
+  let unattributedTotal = 0;
+
+  for (const day of breakdown.data) {
+    const services = Array.isArray(day.services) ? day.services : [];
+    const projectRows = services.filter((s) => projectMatches(s, projectId, projectName));
+    const unattributedRows = services.filter((s) => !s.projectId && !s.project);
+    for (const r of projectRows) projectTotal += (r.billedCost ?? r.cost ?? 0);
+    for (const r of unattributedRows) unattributedTotal += (r.billedCost ?? r.cost ?? 0);
+    if (projectRows.length === 0) continue;
+    matchedAny = true;
+    out.breakdown.data.push({ ...day, services: projectRows });
+  }
+
+  if (!matchedAny) return { filtered: null, matched: false, unattributedTotal };
+
+  out.services = aggregateServicesByName(out.breakdown.data);
+  out.totals = { billedCost: projectTotal };
+  return { filtered: out, matched: true, unattributedTotal };
+}
+
+function projectMatches(serviceRow, projectId, projectName = null) {
+  if (!serviceRow) return false;
+  if (serviceRow.projectId === projectId) return true;
+  if (projectName && serviceRow.name === projectName) return true;
+  if (projectName && serviceRow.project === projectName) return true;
+  if (serviceRow.project === projectId) return true;
+  if (serviceRow.project && (serviceRow.project.id === projectId || serviceRow.project.projectId === projectId || serviceRow.project.name === projectName)) return true;
+  return false;
+}
+
+function aggregateServicesByName(days) {
+  const byName = new Map();
+  for (const day of days) {
+    for (const s of (day.services ?? [])) {
+      const key = s.name ?? '(unnamed)';
+      const prev = byName.get(key) ?? { name: key, billedCost: 0, pricingQuantity: 0, pricingUnit: s.pricingUnit ?? null };
+      prev.billedCost += (s.billedCost ?? s.cost ?? 0);
+      prev.pricingQuantity += (s.pricingQuantity ?? 0);
+      byName.set(key, prev);
+    }
+  }
+  return Array.from(byName.values()).sort((a, b) => (b.billedCost ?? 0) - (a.billedCost ?? 0));
+}
+
+export async function getContract(scope) {
+  const r = await runVercelJson(scopedArgs(['contract', '--format', 'json'], scope));
+  return r.ok ? r.data : null;
+}
+
+export async function getAccountPlan(scope) {
+  const currentTeamId = scope ? null : await getCurrentTeamId();
+  const teamScope = scope || currentTeamId;
+
+  if (teamScope && !String(teamScope).startsWith('usr_')) {
+    const team = await getBillingPlanFromPath(`/v2/teams/${encodeURIComponent(teamScope)}`, 'team.billing.plan');
+    if (team.plan !== 'unknown' || !/not_found|404/i.test(String(team.error ?? ''))) {
+      return team;
+    }
+    // Older project links can carry a user/org id instead of a team id. If the
+    // team lookup misses, fall back to the authenticated user's billing record.
+  }
+
+  return await getBillingPlanFromPath('/v2/user', 'user.billing.plan');
+}
+
+async function getCurrentTeamId() {
+  const identity = await getCliIdentity();
+  return identity?.team?.id ?? null;
+}
+
+async function getBillingPlanFromPath(path, source) {
+  const r = await runVercelJson(['api', path]);
+  if (!r.ok) {
+    return {
+      plan: 'unknown',
+      reason: `${source} unavailable (${r.code ?? 'unknown'})`,
+      source,
+      error: r.code ?? 'unknown',
+    };
+  }
+
+  const parsed = extractBillingPlan(r.data);
+  if (!parsed) {
+    return {
+      plan: 'unknown',
+      reason: `${source} missing from Vercel API response`,
+      source,
+    };
+  }
+
+  return {
+    ...parsed,
+    reason: `${source}=${parsed.plan}`,
+    source,
+  };
+}
+
+export function extractBillingPlan(data) {
+  const raw =
+    data?.billing?.plan ??
+    data?.team?.billing?.plan ??
+    data?.user?.billing?.plan ??
+    null;
+  const plan = normalizeBillingPlan(raw);
+  return plan ? { plan, rawPlan: raw } : null;
+}
+
+function normalizeBillingPlan(raw) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (value === 'hobby' || value === 'pro' || value === 'enterprise') return value;
+  return null;
+}
+
+// Primary source: billing.plan from `/v2/teams/:team` or `/v2/user`.
+// Fallbacks: contract category, then recent billed usage for legacy CLI/API gaps.
+export function inferPlan(contract, opts = {}) {
+  const accountPlan = extractPlanOption(opts?.accountPlan);
+  if (accountPlan) {
+    return {
+      plan: accountPlan.plan,
+      reason: accountPlan.reason ?? `${accountPlan.source ?? 'billing.plan'}=${accountPlan.plan}`,
+    };
+  }
+
+  const commits = contract?.commitments ?? [];
+
+  if (commits.length > 0) {
+    const c0 = commits[0] ?? {};
+    // category field names are tentative — try several.
+    const category = c0.category ?? c0.commitmentCategory ?? c0.type ?? null;
+    if (category === 'Spend' || category === 'spend') {
+      return { plan: 'pro', reason: `commitment category=${category}` };
+    }
+    if (category === 'Usage' || category === 'usage') {
+      return { plan: 'enterprise', reason: `commitment category=${category}` };
+    }
+    return { plan: 'uncertain', reason: `unknown commitment category=${category}` };
+  }
+
+  const totalCost = opts?.usageTotalCost;
+  if (typeof totalCost === 'number' && totalCost > 0) {
+    return {
+      plan: 'pro',
+      reason: `commitments=[] but usage=$${totalCost.toFixed(2)}/window — Pro pay-as-you-go (Hobby teams don't bill)`,
+    };
+  }
+
+  return {
+    plan: 'uncertain',
+    reason: typeof totalCost === 'number' && totalCost === 0
+      ? 'no commitments and no billed usage in window (could be Hobby, or Pro with no recent billing)'
+      : 'no commitments on contract; usage unavailable',
+  };
+}
+
+function extractPlanOption(accountPlan) {
+  if (!accountPlan) return null;
+  if (typeof accountPlan === 'string') {
+    const plan = normalizeBillingPlan(accountPlan);
+    return plan ? { plan, reason: `billing.plan=${plan}` } : null;
+  }
+
+  const plan = normalizeBillingPlan(accountPlan.plan);
+  if (!plan) return null;
+  return {
+    plan,
+    reason: accountPlan.reason ?? (
+      accountPlan.source
+        ? `${accountPlan.source}=${plan}`
+        : `billing.plan=${plan}`
+    ),
+    source: accountPlan.source ?? null,
+  };
+}
+
+export async function detectStack(cwd = process.cwd()) {
+  const pkgPath = join(cwd, 'package.json');
+  let pkg = {};
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+  } catch {
+    return baselineStack();
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  const framework =
+    deps.next ? 'next' :
+    deps.nuxt ? 'nuxt' :
+    deps.astro ? 'astro' :
+    deps['@sveltejs/kit'] ? 'sveltekit' :
+    deps['@remix-run/react'] ? 'remix' :
+    deps.hono ? 'hono' :
+    'unknown';
+
+  const frameworkVersion = (() => {
+    const m = { next: 'next', nuxt: 'nuxt', astro: 'astro', sveltekit: '@sveltejs/kit', remix: '@remix-run/react', hono: 'hono' };
+    const dep = m[framework];
+    if (!dep) return null;
+    return (deps[dep] || '').replace(/^[\^~]/, '') || null;
+  })();
+
+  const hasAppRouter = await pathExists(join(cwd, 'app')) || await pathExists(join(cwd, 'src/app'));
+  const hasPagesRouter = await pathExists(join(cwd, 'pages')) || await pathExists(join(cwd, 'src/pages'));
+  const typescript = await pathExists(join(cwd, 'tsconfig.json'));
+  const cacheComponents = framework === 'next'
+    ? await detectNextCacheComponents(cwd)
+    : null;
+
+  const orm =
+    deps.prisma || deps['@prisma/client'] ? 'prisma' :
+    deps['drizzle-orm'] ? 'drizzle' :
+    deps.kysely ? 'kysely' :
+    'none';
+  const vercelFlagsPackages = [
+    '@vercel/flags',
+    '@vercel/flags/next',
+    '@vercel/flags/sveltekit',
+    '@vercel/flags/nuxt',
+  ].filter((name) => deps[name]);
+  const workflowPackages = Object.keys(deps)
+    .filter((name) => name === 'workflow' || name.startsWith('@workflow/'))
+    .sort();
+
+  const isMonorepo =
+    !!pkg.workspaces ||
+    await pathExists(join(cwd, 'pnpm-workspace.yaml')) ||
+    await pathExists(join(cwd, 'lerna.json'));
+
+  return {
+    framework,
+    frameworkVersion,
+    hasAppRouter,
+    hasPagesRouter,
+    cacheComponents,
+    typescript,
+    orm,
+    isMonorepo,
+    rootDirectory: null,
+    hasVercelFlagsPackage: vercelFlagsPackages.length > 0,
+    vercelFlagsPackages,
+    hasWorkflowPackage: workflowPackages.length > 0,
+    workflowPackages,
+  };
+}
+
+function baselineStack() {
+  return {
+    framework: 'unknown', frameworkVersion: null,
+    hasAppRouter: false, hasPagesRouter: false, cacheComponents: null, typescript: false,
+    orm: 'none', isMonorepo: false, rootDirectory: null,
+    hasVercelFlagsPackage: false, vercelFlagsPackages: [],
+    hasWorkflowPackage: false, workflowPackages: [],
+  };
+}
+
+async function detectNextCacheComponents(cwd) {
+  for (const name of ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs']) {
+    try {
+      const content = await readFile(join(cwd, name), 'utf-8');
+      if (/\bcacheComponents\s*:\s*true\b/.test(content)) return true;
+      if (/\bcacheComponents\s*:\s*false\b/.test(content)) return false;
+    } catch {}
+  }
+  return null;
+}
+
+async function pathExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+// `--scope <teamId>` is buggy on several subcommands (silently falls back to
+// currentTeam). Resolve raw account IDs to slugs/usernames before scoped calls.
+function scopedArgs(args, scope) {
+  if (!scope) return args;
+  if (typeof scope === 'string' && /^(team|usr)_/.test(scope)) {
+    throw new Error('RAW_ID_SCOPE_UNRESOLVED: resolve the linked org/user ID to a CLI scope slug before running Vercel commands.');
+  }
+  return [...args, '--scope', scope];
+}
+
+// CLI summary field is `<metric_id_with_underscores>_<aggregation>` (e.g. `vercel_request_count_sum`).
+export function normalizeSummary(metricResponse, metricId, aggregation, groupBy = []) {
+  if (!metricResponse || metricResponse.error) return [];
+  const field = `${metricId.replace(/\./g, '_')}_${aggregation}`;
+  const rows = Array.isArray(metricResponse.summary) ? metricResponse.summary : [];
+  return rows.map((row) => {
+    const out = { value: row[field] ?? null };
+    for (const dim of groupBy) {
+      if (row[dim] !== undefined) out[dim] = row[dim];
+    }
+    return out;
+  });
+}