@everystack/cli 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -29,6 +29,10 @@
       "types": "./src/cli/model-api.ts",
       "default": "./src/cli/model-api.ts"
     },
+    "./audit": {
+      "types": "./src/cli/audit-api.ts",
+      "default": "./src/cli/audit-api.ts"
+    },
     "./client": {
       "types": "./src/client/index.ts",
       "default": "./src/client/index.ts"

package/src/cli/audit-api.ts

@@ -0,0 +1,54 @@
+/**
+ * Public audit surface — `@everystack/cli/audit`.
+ *
+ * The governance MCP imports these pure scanners directly to gate authoring and
+ * pre-deploy: the secret-leak checks (bundle-audit) and the weight/size checks
+ * (bundle-weight), plus the bundle composition helpers they build on. Pure,
+ * filesystem-free, no CLI/IO coupling — feed them text or {path, size} lists.
+ */
+
+export {
+  // types
+  type AuditFinding,
+  type SecretPattern,
+  // leak scanners
+  SECRET_PATTERNS,
+  redact,
+  isPublicEnvKey,
+  scanSecretShapes,
+  extractBundleUrls,
+  extractExtraEnvKeys,
+  classifyPrivateEnvKeys,
+  scanSecretValue,
+  summarize,
+} from './bundle-audit.js';
+
+export {
+  // types
+  type AssetFile,
+  type AssetKind,
+  type WeightBudget,
+  // weight scanners
+  DEFAULT_WEIGHT_BUDGET,
+  classifyAsset,
+  formatBytes,
+  scanAssetWeights,
+  scanTotalWeight,
+  scanJsWeight,
+  scanSourceMapsPresent,
+  scanDependencyWeight,
+  resolveWeightBudget,
+} from './bundle-weight.js';
+
+export {
+  // composition (input to scanDependencyWeight)
+  type Composition,
+  type ChunkInput,
+  type ChunkSize,
+  type SourceMap,
+  measureChunk,
+  measureChunks,
+  totalSizes,
+  bucketSource,
+  composeSourceMap,
+} from './bundle.js';

package/src/cli/bundle-audit.ts

@@ -0,0 +1,185 @@
+/**
+ * Bundle secret-leak audit — pure scanners for `everystack bundle:audit`.
+ *
+ * Scans the *served* client bundle for leaked secrets. Config-free by leaning on
+ * universal truths instead of a hand-maintained deny-list:
+ *
+ *   1. Generic secret SHAPES (Postgres/Mongo/Redis URLs, sk_live_, AKIA…, PEM
+ *      blocks) — these match a secret's *value* regardless of its key name.
+ *   2. The Expo convention: Metro only inlines `EXPO_PUBLIC_*` env vars into the
+ *      client bundle. Any *other* env key serialized into the bundle is, by
+ *      definition, a private value that leaked.
+ *   3. (Operator-run) value canary: grep the bundle for the literal values of the
+ *      deployed secrets — the only way to catch a Metro-inlined value whose key
+ *      name never appears. Values are redacted in output; never printed.
+ *
+ * Nothing here reads secret values; the canary matcher receives them from the
+ * command's operator-run path.
+ */
+
+export interface AuditFinding {
+  severity: 'fail' | 'warn';
+  check:
+    // leak checks (this file)
+    | 'secret-shape'
+    | 'source-map'
+    | 'private-env-key'
+    | 'secret-value'
+    // weight/size checks (bundle-weight.ts)
+    | 'asset-weight'
+    | 'total-weight'
+    | 'data-in-bundle'
+    | 'js-weight'
+    | 'dep-weight';
+  source: string;
+  detail: string;
+}
+
+export interface SecretPattern {
+  name: string;
+  re: RegExp;
+}
+
+/** Generic, app-agnostic secret shapes. A value matching any of these in a
+ *  client bundle is a leak no matter what env key carried it. */
+export const SECRET_PATTERNS: SecretPattern[] = [
+  { name: 'postgres-url-with-credentials', re: /postgres(?:ql)?:\/\/[^:\s'"`]+:[^@\s'"`]+@/ },
+  { name: 'mongodb-url-with-credentials', re: /mongodb(?:\+srv)?:\/\/[^:\s'"`]+:[^@\s'"`]+@/ },
+  { name: 'redis-url-with-credentials', re: /redis:\/\/[^:\s'"`]*:[^@\s'"`]+@/ },
+  { name: 'stripe-secret-key', re: /sk_(?:live|test)_[A-Za-z0-9]{10,}/ },
+  { name: 'mapbox-secret-token', re: /sk\.[A-Za-z0-9_-]{60,}/ },
+  { name: 'sendgrid-key', re: /SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/ },
+  { name: 'google-api-key', re: /AIza[0-9A-Za-z_-]{35}/ },
+  { name: 'github-token', re: /gh[pousr]_[A-Za-z0-9]{36,}/ },
+  { name: 'slack-token', re: /xox[baprs]-[A-Za-z0-9-]{10,}/ },
+  { name: 'aws-access-key-id', re: /AKIA[0-9A-Z]{16}/ },
+  { name: 'pem-private-key', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
+  { name: 'generic-credentials-in-url', re: /\b[a-z][a-z0-9+.-]*:\/\/[A-Za-z0-9._%-]+:[^@\s'"`/]{6,}@/ },
+];
+
+/** Mask a matched secret so the output never prints it in full. */
+export function redact(s: string): string {
+  if (s.length <= 6) return '******';
+  return `${s.slice(0, 4)}…${s.slice(-2)} (${s.length} chars)`;
+}
+
+/** True if an env key is client-public by Expo convention (Metro-inlined). */
+export function isPublicEnvKey(key: string): boolean {
+  return key.startsWith('EXPO_PUBLIC_');
+}
+
+/** Scan one artifact's text for generic secret shapes. Matches are redacted. */
+export function scanSecretShapes(text: string, source: string): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  const seen = new Set<string>(); // dedupe overlapping patterns on the same span
+  for (const { name, re } of SECRET_PATTERNS) {
+    const m = re.exec(text);
+    if (m && !seen.has(m[0])) {
+      seen.add(m[0]);
+      findings.push({
+        severity: 'fail',
+        check: 'secret-shape',
+        source,
+        detail: `${name}: ${redact(m[0])}`,
+      });
+    }
+  }
+  return findings;
+}
+
+/** Extract client JS bundle URLs from served HTML (Expo web export convention). */
+export function extractBundleUrls(html: string): string[] {
+  const urls = new Set<string>();
+  const re = /["'(]([^"'()]*_expo\/static\/js\/web\/[^"'()?]+\.js)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(html)) !== null) {
+    urls.add(m[1].replace(/^\.?\//, ''));
+  }
+  return [...urls];
+}
+
+/**
+ * Extract served *static asset* references (images, data files, fonts, css)
+ * from a bundle/HTML — anything under `assets/` or `_expo/static/` that is not
+ * JS or a source map (those are crawled / gated separately). Used by the remote
+ * weight scan to discover what to HEAD for its size without downloading it.
+ */
+export function extractAssetUrls(text: string): string[] {
+  const urls = new Set<string>();
+  const re = /["'(]((?:\.?\/)?(?:assets|_expo\/static)\/[^"'()\s]+?\.[A-Za-z0-9]+)(?:\?[^"'()\s]*)?["')]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    const rel = m[1].replace(/^\.?\//, '');
+    if (/\.(?:js|mjs|cjs|map)$/i.test(rel)) continue;
+    urls.add(rel);
+  }
+  return [...urls];
+}
+
+const EXTRA_KEY_SKIP = new Set([
+  'JSON', 'URL', 'GET', 'POST', 'PUT', 'DELETE', 'HEAD', 'OPTIONS', 'PATCH',
+  'API', 'HTTP', 'HTTPS', 'UTF', 'UUID', 'ID', 'OK', 'EAS',
+]);
+
+/**
+ * Best-effort extraction of ALL-CAPS env-looking keys serialized near an
+ * `"extra"` region of the bundle (where Expo embeds app.config `extra`). No EAS
+ * projectId anchor needed — we scan a window around each `"extra"` occurrence.
+ */
+export function extractExtraEnvKeys(text: string, window = 600): string[] {
+  const keys = new Set<string>();
+  const keyRe = /["']([A-Z][A-Z0-9_]{2,})["']\s*:/g;
+  let idx = text.indexOf('"extra"');
+  while (idx !== -1) {
+    const region = text.slice(idx, idx + window);
+    let m: RegExpExecArray | null;
+    keyRe.lastIndex = 0;
+    while ((m = keyRe.exec(region)) !== null) {
+      if (!EXTRA_KEY_SKIP.has(m[1])) keys.add(m[1]);
+    }
+    idx = text.indexOf('"extra"', idx + 1);
+  }
+  return [...keys];
+}
+
+/** Flag any non-EXPO_PUBLIC env key found embedded in the bundle's extra. */
+export function classifyPrivateEnvKeys(keys: string[], source: string): AuditFinding[] {
+  return keys
+    .filter((k) => !isPublicEnvKey(k))
+    .map((k) => ({
+      severity: 'fail' as const,
+      check: 'private-env-key' as const,
+      source,
+      detail: `${k} is embedded in the bundle but is not EXPO_PUBLIC_* — a private value leaked`,
+    }));
+}
+
+/**
+ * Operator-run value canary: does the bundle contain the literal secret value?
+ * Returns a finding with the value REDACTED (replaced by a [KEY] marker) — the
+ * raw value is never placed in the output.
+ */
+export function scanSecretValue(
+  text: string,
+  key: string,
+  value: string,
+  source: string,
+): AuditFinding | null {
+  if (isPublicEnvKey(key)) return null; // public by design
+  if (value.length < 8) return null; // too short to be a meaningful secret
+  const at = text.indexOf(value);
+  if (at === -1) return null;
+  return {
+    severity: 'fail',
+    check: 'secret-value',
+    source,
+    detail: `value of ${key} appears verbatim in the bundle (Metro-inlined leak) [${redact(value)}]`,
+  };
+}
+
+export function summarize(findings: AuditFinding[]): { fail: number; warn: number } {
+  return {
+    fail: findings.filter((f) => f.severity === 'fail').length,
+    warn: findings.filter((f) => f.severity === 'warn').length,
+  };
+}

package/src/cli/bundle-weight.ts

@@ -0,0 +1,356 @@
+/**
+ * Bundle weight/size audit — pure scanners for `everystack bundle:audit`.
+ *
+ * The leak scanner (bundle-audit.ts) answers "did a secret get into the bundle?"
+ * This answers "is the bundle bloated, and is data shipping that belongs in the
+ * database?" — the class of mistake test-case-zero is made of: an agent that
+ * defaults to training-consensus and bundles a 180MB JSON into an Expo app.
+ *
+ * Config-free by construction. The only inputs are universal truths:
+ *   - a file's byte size (the budget gate),
+ *   - its extension (data vs image vs js vs source-map vs other),
+ *   - and, when a source map is present, the per-package source-byte breakdown
+ *     already computed by bundle.ts (the dependency-weight gate).
+ *
+ * Everything here is pure: it takes a list of {path, size} and returns findings.
+ * The command layer walks the export directory (and the app source tree) and
+ * feeds those lists in, so the governance MCP can import these scanners directly
+ * without touching the filesystem.
+ */
+
+import type { AuditFinding } from './bundle-audit.js';
+import type { Composition } from './bundle.js';
+
+/** One file's relative path and byte size — the only input the gates need. */
+export interface AssetFile {
+  path: string;
+  size: number;
+}
+
+export type AssetKind = 'data' | 'image' | 'js' | 'sourcemap' | 'other';
+
+/** Per-file and total byte budgets. All sizes are bytes. */
+export interface WeightBudget {
+  /** Generic single-file warn/fail (non-data, non-image, non-js). */
+  perFileWarn: number;
+  perFileFail: number;
+  /** An image past this is almost certainly unoptimized. */
+  imageWarn: number;
+  /** Sum of every file in the export. */
+  totalWarn: number;
+  totalFail: number;
+  /** Sum of served client JS chunks. */
+  jsWarn: number;
+  jsFail: number;
+  /** A data file (.json/.csv/…) shipped in the bundle. Categorically suspect:
+   *  data belongs in the DB/Model/API, so the thresholds are tighter. */
+  dataWarn: number;
+  dataFail: number;
+  /** A single dependency's source-byte contribution (from the source map). */
+  depWarn: number;
+  /** …or its share of the largest chunk, whichever trips first. */
+  depShareWarn: number;
+}
+
+const MB = 1024 * 1024;
+
+/**
+ * Defaults chosen against real Expo/mobile norms, not arbitrary round numbers:
+ *  - Optimized images sit well under 1MB; a 2MB+ non-image asset is unusual and
+ *    a 10MB single file is almost always a mistake.
+ *  - Data files belong in the DB, so they fail tighter (5MB) with a redirect
+ *    message — a 180MB JSON trips this loudly.
+ *  - A typical Expo web client bundle is a few MB raw; 15MB+ is bloat.
+ *  - A single dependency over ~512KB of source, or dominating >25% of the
+ *    largest chunk, is worth a second look.
+ * All overridable via flags (resolveWeightBudget).
+ */
+export const DEFAULT_WEIGHT_BUDGET: WeightBudget = {
+  perFileWarn: 2 * MB,
+  perFileFail: 10 * MB,
+  imageWarn: 1 * MB,
+  totalWarn: 25 * MB,
+  totalFail: 100 * MB,
+  jsWarn: 5 * MB,
+  jsFail: 15 * MB,
+  dataWarn: 1 * MB,
+  dataFail: 5 * MB,
+  depWarn: 512 * 1024,
+  depShareWarn: 0.25,
+};
+
+const DATA_EXTS = new Set([
+  '.json', '.csv', '.tsv', '.geojson', '.ndjson', '.jsonl',
+  '.xml', '.yaml', '.yml', '.parquet', '.sqlite', '.db',
+]);
+const IMAGE_EXTS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.tiff', '.tif', '.avif',
+]);
+
+function ext(p: string): string {
+  const dot = p.lastIndexOf('.');
+  return dot < 0 ? '' : p.slice(dot).toLowerCase();
+}
+
+/** Classify a file by extension — the basis of every weight gate. */
+export function classifyAsset(p: string): AssetKind {
+  const e = ext(p);
+  if (e === '.map') return 'sourcemap';
+  if (e === '.js' || e === '.mjs' || e === '.cjs') return 'js';
+  if (DATA_EXTS.has(e)) return 'data';
+  if (IMAGE_EXTS.has(e)) return 'image';
+  return 'other';
+}
+
+/** Human-readable byte size: "180.00 MB", "512.00 KB", "40 B". */
+export function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < MB) return `${(n / 1024).toFixed(2)} KB`;
+  if (n < 1024 * MB) return `${(n / MB).toFixed(2)} MB`;
+  return `${(n / (1024 * MB)).toFixed(2)} GB`;
+}
+
+/**
+ * Per-file weight gate over data / image / other assets. JS and source maps are
+ * skipped here (scanJsWeight / scanSourceMapsPresent own those). A data file
+ * over budget is reported as `data-in-bundle` with the "belongs in the DB"
+ * redirect; an oversized image is called out as unoptimized.
+ */
+export function scanAssetWeights(
+  files: AssetFile[],
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  for (const f of files) {
+    const kind = classifyAsset(f.path);
+    if (kind === 'js' || kind === 'sourcemap') continue;
+
+    if (kind === 'data') {
+      if (f.size >= budget.dataFail) {
+        findings.push({
+          severity: 'fail',
+          check: 'data-in-bundle',
+          source: f.path,
+          detail: `${f.path} is ${formatBytes(f.size)} of data shipped in the bundle — this belongs in the database (a Model/migration) and should be served over the API, not bundled`,
+        });
+      } else if (f.size >= budget.dataWarn) {
+        findings.push({
+          severity: 'warn',
+          check: 'data-in-bundle',
+          source: f.path,
+          detail: `${f.path} is ${formatBytes(f.size)} of data in the bundle — consider moving it to the database/API`,
+        });
+      }
+      continue;
+    }
+
+    const warnAt = kind === 'image' ? budget.imageWarn : budget.perFileWarn;
+    if (f.size >= budget.perFileFail) {
+      findings.push({
+        severity: 'fail',
+        check: 'asset-weight',
+        source: f.path,
+        detail:
+          kind === 'image'
+            ? `${f.path} is ${formatBytes(f.size)} — an unoptimized image this large should be compressed or served from a CDN`
+            : `${f.path} is ${formatBytes(f.size)}, over the ${formatBytes(budget.perFileFail)} per-file budget`,
+      });
+    } else if (f.size >= warnAt) {
+      findings.push({
+        severity: 'warn',
+        check: 'asset-weight',
+        source: f.path,
+        detail:
+          kind === 'image'
+            ? `${f.path} is ${formatBytes(f.size)} — large for an image, consider optimizing (WebP/AVIF) or a CDN`
+            : `${f.path} is ${formatBytes(f.size)}, over the ${formatBytes(budget.perFileWarn)} per-file warning budget`,
+      });
+    }
+  }
+  return findings;
+}
+
+/** Total-export-size gate over every file. */
+export function scanTotalWeight(
+  files: AssetFile[],
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): AuditFinding[] {
+  const total = files.reduce((sum, f) => sum + f.size, 0);
+  if (total >= budget.totalFail) {
+    return [
+      {
+        severity: 'fail',
+        check: 'total-weight',
+        source: 'export',
+        detail: `total export is ${formatBytes(total)} across ${files.length} file(s), over the ${formatBytes(budget.totalFail)} budget`,
+      },
+    ];
+  }
+  if (total >= budget.totalWarn) {
+    return [
+      {
+        severity: 'warn',
+        check: 'total-weight',
+        source: 'export',
+        detail: `total export is ${formatBytes(total)} across ${files.length} file(s), over the ${formatBytes(budget.totalWarn)} warning budget`,
+      },
+    ];
+  }
+  return [];
+}
+
+/** Served-client-JS weight gate (sum of all .js chunks). */
+export function scanJsWeight(
+  files: AssetFile[],
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): AuditFinding[] {
+  const js = files.filter((f) => classifyAsset(f.path) === 'js');
+  if (js.length === 0) return [];
+  const total = js.reduce((sum, f) => sum + f.size, 0);
+  if (total >= budget.jsFail) {
+    return [
+      {
+        severity: 'fail',
+        check: 'js-weight',
+        source: 'client-js',
+        detail: `client JS is ${formatBytes(total)} raw across ${js.length} chunk(s), over the ${formatBytes(budget.jsFail)} budget — see the data-in-bundle findings for inlined datasets, or \`everystack bundle:analyze\` for the per-package breakdown`,
+      },
+    ];
+  }
+  if (total >= budget.jsWarn) {
+    return [
+      {
+        severity: 'warn',
+        check: 'js-weight',
+        source: 'client-js',
+        detail: `client JS is ${formatBytes(total)} raw across ${js.length} chunk(s), over the ${formatBytes(budget.jsWarn)} warning budget`,
+      },
+    ];
+  }
+  return [];
+}
+
+/**
+ * Flag source maps present in the export — they will be served to prod and
+ * expose original source. Distinct from the network leak check, which catches a
+ * map already served at a URL; this catches it before deploy.
+ */
+export function scanSourceMapsPresent(files: AssetFile[]): AuditFinding[] {
+  return files
+    .filter((f) => classifyAsset(f.path) === 'sourcemap')
+    .map((f) => ({
+      severity: 'warn' as const,
+      check: 'source-map' as const,
+      source: f.path,
+      detail: `source map (${formatBytes(f.size)}) is in the export and will be served to prod — exclude it from the deployed artifacts`,
+    }));
+}
+
+/**
+ * Best-effort dependency-weight gate from the largest chunk's source-map
+ * composition (bundle.ts → composeSourceMap). A single dependency over the byte
+ * budget, or dominating the chunk by share, is flagged. App workspace buckets
+ * (APP:*) are skipped — they are the app's own code, not a dependency.
+ */
+export function scanDependencyWeight(
+  composition: Composition,
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): AuditFinding[] {
+  const findings: AuditFinding[] = [];
+  for (const p of composition.top) {
+    if (p.pkg.startsWith('APP:')) continue;
+    const overBytes = p.bytes >= budget.depWarn;
+    const overShare = p.share >= budget.depShareWarn;
+    if (overBytes || overShare) {
+      findings.push({
+        severity: 'warn',
+        check: 'dep-weight',
+        source: p.pkg,
+        detail: `${p.pkg} contributes ${formatBytes(p.bytes)} (${(p.share * 100).toFixed(1)}%) to the largest chunk — consider a lighter alternative or lazy-loading`,
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Pinpoint *data inlined into a JS chunk* — the most useful diagnosis, because
+ * a dataset imported into app code (`import data from './big.json'`) is bundled
+ * as a Metro module and shows up only as "JS is big". This splits the chunk on
+ * Metro module boundaries (`__d(`), finds the heavy ones whose body is an
+ * `exports = {…}`/`[…]` literal with high data density (digits/quotes/colons),
+ * and names each with its size and a key hint, redirecting it to the DB/API.
+ *
+ * Pure: takes the chunk text, returns findings. Top offenders only (capped), so
+ * a chunk full of data produces a readable list, not hundreds of lines.
+ */
+export function analyzeChunkBloat(
+  text: string,
+  source: string,
+  budget: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+  topN = 8,
+): AuditFinding[] {
+  const starts: number[] = [];
+  const re = /__d\(/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) starts.push(m.index);
+  if (starts.length === 0) return [];
+
+  const found: AuditFinding[] = [];
+  for (let i = 0; i < starts.length; i++) {
+    const s = starts[i];
+    const e = i + 1 < starts.length ? starts[i + 1] : text.length;
+    const size = e - s;
+    if (size < budget.dataWarn) continue;
+
+    const head = text.slice(s, s + 220);
+    if (!/\.exports\s*=\s*[{[]/.test(head)) continue; // not an export literal
+
+    // Data density on a sample: data files are mostly quotes/digits/punctuation.
+    const sample = text.slice(s, s + 4096);
+    const dataChars = (sample.match(/["{}:,[\]0-9.]/g) || []).length;
+    if (!sample.length || dataChars / sample.length < 0.22) continue; // looks like code
+
+    const hint = (head.match(/exports\s*=\s*[{[]\s*"?([A-Za-z0-9_:.-]{2,40})"?\s*[:,]/) || [])[1];
+    found.push({
+      severity: size >= budget.dataFail ? 'fail' : 'warn',
+      check: 'data-in-bundle',
+      source,
+      detail: `${formatBytes(size)} of data is inlined into ${source}${hint ? ` (a module whose first key is "${hint}")` : ''} — this is a dataset imported into app code; move it to the database (a Model/migration) and serve it over the API instead of bundling it`,
+    });
+  }
+  return found.sort((a, b) => byteHint(b.detail) - byteHint(a.detail)).slice(0, topN);
+}
+
+/** Pull the leading byte count back out of a formatted detail, for sorting. */
+function byteHint(detail: string): number {
+  const m = detail.match(/^([\d.]+)\s*(B|KB|MB|GB)/);
+  if (!m) return 0;
+  const units: Record<string, number> = { B: 1, KB: 1024, MB: MB, GB: 1024 * MB };
+  return parseFloat(m[1]) * (units[m[2]] || 1);
+}
+
+/** The N biggest files, largest first — for an always-on "largest files" list. */
+export function largestFiles(files: AssetFile[], n = 10): AssetFile[] {
+  return [...files].sort((a, b) => b.size - a.size).slice(0, n);
+}
+
+/** Resolve a budget from CLI flags (MB), falling back to the defaults. */
+export function resolveWeightBudget(
+  flags: Record<string, string>,
+  base: WeightBudget = DEFAULT_WEIGHT_BUDGET,
+): WeightBudget {
+  const mb = (key: string): number | undefined => {
+    const raw = flags[key];
+    if (raw == null) return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n * MB : undefined;
+  };
+  return {
+    ...base,
+    perFileFail: mb('max-file-mb') ?? base.perFileFail,
+    totalFail: mb('max-total-mb') ?? base.totalFail,
+    jsFail: mb('max-js-mb') ?? base.jsFail,
+    dataFail: mb('max-data-mb') ?? base.dataFail,
+  };
+}