better-convex 0.6.3 → 0.7.0

package/dist/cli.mjs

@@ -1,13 +1,1909 @@
 #!/usr/bin/env node
-import { t as generateMeta } from "./codegen-DkpPBVPn.mjs";
+import { n as getConvexConfig, t as generateMeta } from "./codegen-Cz1idI3-.mjs";
 import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path, { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execa } from "execa";
+import { createJiti } from "jiti";
+import { v } from "convex/values";
+import { createInterface } from "node:readline/promises";
+import { build } from "esbuild";
 import * as childProcess from "node:child_process";
 import { parse } from "dotenv";
 
+//#region src/orm/builders/column-builder.ts
+/**
+* entityKind symbol for runtime type checking
+* Following Drizzle's pattern for type guards
+*/
+const entityKind = Symbol.for("better-convex:entityKind");
+/**
+* Base ColumnBuilder abstract class
+*
+* All column builders inherit from this class.
+* Implements chaining methods and stores runtime config.
+*/
+var ColumnBuilder = class {
+	static [entityKind] = "ColumnBuilder";
+	[entityKind] = "ColumnBuilder";
+	/**
+	* Runtime configuration - actual mutable state
+	*/
+	config;
+	constructor(name, dataType, columnType) {
+		this.config = {
+			name,
+			notNull: false,
+			default: void 0,
+			hasDefault: false,
+			primaryKey: false,
+			isUnique: false,
+			uniqueName: void 0,
+			uniqueNulls: void 0,
+			foreignKeyConfigs: [],
+			dataType,
+			columnType
+		};
+	}
+	/**
+	* Mark column as NOT NULL
+	* Returns type-branded instance with notNull: true
+	*/
+	notNull() {
+		this.config.notNull = true;
+		return this;
+	}
+	/**
+	* Override the TypeScript type for this column.
+	* Mirrors Drizzle's $type() (type-only, no runtime validation changes).
+	*/
+	$type() {
+		return this;
+	}
+	/**
+	* Set default value for column
+	* Makes field optional on insert
+	*/
+	default(value) {
+		this.config.default = value;
+		this.config.hasDefault = true;
+		return this;
+	}
+	/**
+	* Set default function for column (runtime evaluated on insert).
+	* Mirrors Drizzle's $defaultFn() / $default().
+	*/
+	$defaultFn(fn) {
+		this.config.defaultFn = fn;
+		return this;
+	}
+	/**
+	* Alias of $defaultFn for Drizzle parity.
+	*/
+	$default(fn) {
+		return this.$defaultFn(fn);
+	}
+	/**
+	* Set on-update function for column (runtime evaluated on update).
+	* Mirrors Drizzle's $onUpdateFn() / $onUpdate().
+	*/
+	$onUpdateFn(fn) {
+		this.config.onUpdateFn = fn;
+		return this;
+	}
+	/**
+	* Alias of $onUpdateFn for Drizzle parity.
+	*/
+	$onUpdate(fn) {
+		return this.$onUpdateFn(fn);
+	}
+	/**
+	* Mark column as primary key
+	* Implies NOT NULL
+	*/
+	primaryKey() {
+		this.config.primaryKey = true;
+		this.config.notNull = true;
+		return this;
+	}
+	/**
+	* Mark column as UNIQUE
+	* Mirrors Drizzle column unique API
+	*/
+	unique(name, config) {
+		this.config.isUnique = true;
+		this.config.uniqueName = name;
+		this.config.uniqueNulls = config?.nulls;
+		return this;
+	}
+	/**
+	* Define a foreign key reference
+	* Mirrors Drizzle column references() API
+	*/
+	references(ref, config = {}) {
+		this.config.foreignKeyConfigs.push({
+			ref,
+			config
+		});
+		return this;
+	}
+};
+
+//#endregion
+//#region src/orm/builders/system-fields.ts
+/**
+* System Fields - Convex-provided fields available on all documents
+*
+* id: Document ID (string, backed by internal Convex _id)
+* createdAt: Creation timestamp alias (backed by internal Convex _creationTime)
+*
+* These are automatically added to every Convex table.
+*/
+var ConvexSystemIdBuilder = class extends ColumnBuilder {
+	static [entityKind] = "ConvexSystemIdBuilder";
+	[entityKind] = "ConvexSystemIdBuilder";
+	constructor() {
+		super("_id", "string", "ConvexSystemId");
+		this.config.notNull = true;
+	}
+	build() {
+		return v.string();
+	}
+	/**
+	* Convex validator - runtime access
+	* System fields use v.string() for _id
+	*/
+	get convexValidator() {
+		return this.build();
+	}
+};
+var ConvexSystemCreationTimeBuilder = class extends ColumnBuilder {
+	static [entityKind] = "ConvexSystemCreationTimeBuilder";
+	[entityKind] = "ConvexSystemCreationTimeBuilder";
+	constructor() {
+		super("_creationTime", "number", "ConvexSystemCreationTime");
+		this.config.notNull = true;
+	}
+	build() {
+		return v.number();
+	}
+	/**
+	* Convex validator - runtime access
+	* System fields use v.number() for _creationTime
+	*/
+	get convexValidator() {
+		return this.build();
+	}
+};
+var ConvexSystemCreatedAtBuilder = class extends ColumnBuilder {
+	static [entityKind] = "ConvexSystemCreatedAtBuilder";
+	[entityKind] = "ConvexSystemCreatedAtBuilder";
+	constructor() {
+		super("_creationTime", "number", "ConvexSystemCreatedAt");
+		this.config.notNull = true;
+	}
+	build() {
+		return v.number();
+	}
+	get convexValidator() {
+		return this.build();
+	}
+};
+function createSystemFields(tableName) {
+	const id = new ConvexSystemIdBuilder();
+	const creationTime = new ConvexSystemCreationTimeBuilder();
+	const createdAt = new ConvexSystemCreatedAtBuilder();
+	id.config.tableName = tableName;
+	creationTime.config.tableName = tableName;
+	createdAt.config.tableName = tableName;
+	return {
+		id,
+		_creationTime: creationTime,
+		createdAt
+	};
+}
+
+//#endregion
+//#region src/orm/index-utils.ts
+function getIndexes(table) {
+	const indexes = table.getIndexes?.();
+	return Array.isArray(indexes) ? indexes : [];
+}
+function getAggregateIndexes(table) {
+	const indexes = table.getAggregateIndexes?.();
+	return Array.isArray(indexes) ? indexes : [];
+}
+function getRankIndexes(table) {
+	const indexes = table.getRankIndexes?.();
+	return Array.isArray(indexes) ? indexes : [];
+}
+
+//#endregion
+//#region src/orm/symbols.ts
+const TableName = Symbol.for("better-convex:TableName");
+const Columns = Symbol.for("better-convex:Columns");
+const Brand = Symbol.for("better-convex:Brand");
+const Relations = Symbol.for("better-convex:Relations");
+const OrmContext = Symbol.for("better-convex:OrmContext");
+const RlsPolicies = Symbol.for("better-convex:RlsPolicies");
+const EnableRLS = Symbol.for("better-convex:EnableRLS");
+const TableDeleteConfig = Symbol.for("better-convex:TableDeleteConfig");
+const OrmSchemaOptions = Symbol.for("better-convex:OrmSchemaOptions");
+const OrmSchemaDefinition = Symbol.for("better-convex:OrmSchemaDefinition");
+
+//#endregion
+//#region src/orm/mutation-utils.ts
+const UTF8_ENCODER = new TextEncoder();
+function getTableName(table) {
+	const name = table.tableName ?? table[TableName] ?? table?._?.name;
+	if (!name) throw new Error("Table is missing a name");
+	return name;
+}
+function getUniqueIndexes(table) {
+	const fromMethod = table.getUniqueIndexes?.();
+	if (Array.isArray(fromMethod)) return fromMethod;
+	const fromField = table.uniqueIndexes;
+	return Array.isArray(fromField) ? fromField : [];
+}
+function getChecks(table) {
+	const fromMethod = table.getChecks?.();
+	if (Array.isArray(fromMethod)) return fromMethod;
+	const fromField = table.checks;
+	return Array.isArray(fromField) ? fromField : [];
+}
+function getForeignKeys(table) {
+	const fromMethod = table.getForeignKeys?.();
+	if (Array.isArray(fromMethod)) return fromMethod;
+	const fromField = table.foreignKeys;
+	return Array.isArray(fromField) ? fromField : [];
+}
+
+//#endregion
+//#region src/orm/introspection.ts
+function getSystemFields(table) {
+	if (table.id && table._creationTime) return {
+		id: table.id,
+		createdAt: table._creationTime ?? table.createdAt
+	};
+	const system = createSystemFields(getTableName(table));
+	for (const builder of Object.values(system)) builder.config.table = table;
+	return {
+		id: system.id,
+		createdAt: system.createdAt
+	};
+}
+function getTableColumns(table) {
+	return {
+		...table[Columns] ?? {},
+		...getSystemFields(table)
+	};
+}
+function getTableConfig(table) {
+	const policies = table.getRlsPolicies?.() ?? table[RlsPolicies] ?? [];
+	const enabled = table.isRlsEnabled?.() ?? table[EnableRLS] ?? false;
+	return {
+		name: getTableName(table),
+		columns: getTableColumns(table),
+		indexes: getIndexes(table),
+		aggregateIndexes: getAggregateIndexes(table),
+		rankIndexes: getRankIndexes(table),
+		uniqueIndexes: getUniqueIndexes(table),
+		foreignKeys: getForeignKeys(table),
+		checks: getChecks(table),
+		rls: {
+			enabled,
+			policies
+		}
+	};
+}
+
+//#endregion
+//#region src/cli/analyze.ts
+const MB = 1024 * 1024;
+const DEFAULT_WARNING_MB = 6;
+const DEFAULT_DANGER_MB = 8;
+const DEFAULT_TOP_INPUTS = 12;
+const DEFAULT_TOP_PACKAGES = 12;
+const DEFAULT_DETAIL_ENTRIES = 20;
+const DEFAULT_OUTPUT_WIDTH = 120;
+const SMALL_INPUT_MIN_BYTES = 8 * 1024;
+const SMALL_INPUT_MIN_SHARE = .002;
+const WHITESPACE_SPLIT_REGEX = /\s+/;
+const NEWLINE_SPLIT_REGEX = /\r?\n/;
+const ENTRY_POINT_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+]);
+const SCHEMA_RESOLVE_FILTER = /^\.{1,2}\/schema(\.ts|\.js)?$/;
+const USE_NODE_DIRECTIVE_REGEX = /^\s*("|')use node\1;?\s*$/;
+const VALID_IDENTIFIER_REGEX = /^[a-zA-Z_$][\w$]*$/;
+const EXPORTED_CONST_CAPTURE_REGEX = /export\s+const\s+([a-zA-Z_$][\w$]*)\s*=/g;
+const CHAINED_PROCEDURE_CAPTURE_REGEX = /\.\s*(?:query|mutation|action)\s*\(/;
+const EXPORTED_NATIVE_HANDLER_CAPTURE_REGEX = /export\s+const\s+([a-zA-Z_$][\w$]*)\s*=\s*(?:[\w$]+\.)?(?:query|mutation|action|internalQuery|internalMutation|internalAction)\s*\(/g;
+const EXPORTED_ORM_API_DESTRUCTURE_CAPTURE_REGEX = /export\s+const\s*\{([^}]+)\}\s*=\s*orm\.api\s*\(\s*\)\s*;?/g;
+const supportsColor = process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+const isInteractiveTerminal = process.stdin.isTTY && process.stdout.isTTY;
+let colorEnabled = supportsColor;
+let outputWidth = process.stdout.columns ?? DEFAULT_OUTPUT_WIDTH;
+const ANSI = {
+	reset: "\x1B[0m",
+	bold: "\x1B[1m",
+	dim: "\x1B[2m",
+	red: "\x1B[31m",
+	yellow: "\x1B[33m",
+	green: "\x1B[32m",
+	cyan: "\x1B[36m",
+	magenta: "\x1B[35m",
+	gray: "\x1B[90m"
+};
+const dedupe = (values) => Array.from(new Set(values));
+const formatBytes = (bytes) => `${(bytes / MB).toFixed(2)} MB`;
+const toMB = (bytes) => (bytes / MB).toFixed(2);
+const truncate = (value, maxWidth) => {
+	if (value.length <= maxWidth) return value;
+	if (maxWidth <= 3) return value.slice(0, maxWidth);
+	return `${value.slice(0, maxWidth - 3)}...`;
+};
+const pad = (value, width, align = "left") => {
+	if (align === "right") return value.padStart(width, " ");
+	return value.padEnd(width, " ");
+};
+const colorize = (value, color) => {
+	if (!colorEnabled) return value;
+	return `${color}${value}${ANSI.reset}`;
+};
+const bold = (value) => colorize(value, ANSI.bold);
+const dim = (value) => colorize(value, ANSI.dim);
+const shareColor = (sharePercent) => {
+	if (sharePercent >= 25) return ANSI.red;
+	if (sharePercent >= 10) return ANSI.yellow;
+	if (sharePercent >= 3) return ANSI.cyan;
+	return ANSI.gray;
+};
+const severityColor = (severity) => {
+	if (severity === "DANGER") return ANSI.red;
+	if (severity === "WARN") return ANSI.yellow;
+	return ANSI.green;
+};
+const makeShareBar = (sharePercent, width = 16) => {
+	const clamped = Math.max(0, Math.min(100, sharePercent));
+	const filled = Math.round(clamped / 100 * width);
+	return colorize(`${"#".repeat(filled)}${".".repeat(Math.max(0, width - filled))}`, shareColor(sharePercent));
+};
+const colorizePadded = (value, width, align, color) => colorize(pad(value, width, align), color);
+const ANSI_PATTERN = new RegExp(`\\x1b\\[[0-9;]*m`, "g");
+const visibleLength = (value) => value.replace(ANSI_PATTERN, "").length;
+const wrapPlain = (text, width) => {
+	const maxWidth = Math.max(16, width);
+	const words = text.split(WHITESPACE_SPLIT_REGEX).filter(Boolean);
+	if (words.length === 0) return [""];
+	const lines = [];
+	let current = "";
+	for (const word of words) {
+		if (!current) {
+			current = word;
+			continue;
+		}
+		if (current.length + 1 + word.length <= maxWidth) {
+			current += ` ${word}`;
+			continue;
+		}
+		lines.push(current);
+		current = word;
+	}
+	if (current) lines.push(current);
+	return lines;
+};
+const printWrapped = ({ indent = 0, prefix = "", text, color = null }) => {
+	const indentStr = " ".repeat(Math.max(0, indent));
+	const prefixLen = visibleLength(prefix);
+	wrapPlain(text, Math.max(16, outputWidth - indent - prefixLen)).forEach((line, index) => {
+		const leader = index === 0 ? prefix : " ".repeat(prefixLen);
+		const body = color ? colorize(line, color) : line;
+		console.log(`${indentStr}${leader}${body}`);
+	});
+};
+const firstLine = (value) => value.split("\n").at(0) ?? value;
+const normalizeOutputPath = (filePath) => filePath.split(path.sep).join("/");
+const pathHasMultipleDots = (base) => (base.match(/\./g) ?? []).length > 1;
+const shellQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const walkDeployEntryPoints = (dir, options) => {
+	const files = [];
+	const includeMultiDot = options?.includeMultiDot ?? false;
+	const includeGeneratedDir = options?.includeGeneratedDir ?? false;
+	const visit = (currentDir) => {
+		for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+			const fullPath = path.join(currentDir, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === "_generated") continue;
+				if (entry.name === "generated" && !includeGeneratedDir) continue;
+				visit(fullPath);
+				continue;
+			}
+			if (!entry.isFile()) continue;
+			const normalizedRelPath = normalizeOutputPath(path.relative(dir, fullPath));
+			const parsed = path.parse(fullPath);
+			const base = parsed.base;
+			const ext = parsed.ext.toLowerCase();
+			if (normalizedRelPath.startsWith("_deps/")) continue;
+			if (!ENTRY_POINT_EXTENSIONS.has(ext)) continue;
+			if (base.startsWith(".") || base.startsWith("#")) continue;
+			if (base === "schema.ts" || base === "schema.js") continue;
+			if (!includeMultiDot && pathHasMultipleDots(base)) continue;
+			if (normalizedRelPath.includes(" ")) continue;
+			files.push(fullPath);
+		}
+	};
+	visit(dir);
+	return files;
+};
+const detectProjectRoots = () => {
+	const projectRoot = process.cwd();
+	const preferredFunctionsRoot = path.join(projectRoot, "convex", "functions");
+	const fallbackFunctionsRoot = path.join(projectRoot, "convex");
+	if (fs.existsSync(preferredFunctionsRoot)) return {
+		projectRoot,
+		functionsRoot: preferredFunctionsRoot
+	};
+	if (fs.existsSync(fallbackFunctionsRoot)) return {
+		projectRoot,
+		functionsRoot: fallbackFunctionsRoot
+	};
+	throw new Error(`Missing Convex functions directory. Expected one of:\n- ${preferredFunctionsRoot}\n- ${fallbackFunctionsRoot}`);
+};
+const hasUseNodeDirective = (source) => {
+	if (!source.includes("use node")) return false;
+	const lines = source.split(NEWLINE_SPLIT_REGEX);
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		if (trimmed.startsWith("//")) continue;
+		if (trimmed.startsWith("/*")) continue;
+		return USE_NODE_DIRECTIVE_REGEX.test(trimmed);
+	}
+	return false;
+};
+const isNodeEntryPoint = (entryPoint, functionsRoot) => {
+	if (normalizeOutputPath(path.relative(functionsRoot, entryPoint)).startsWith("actions/")) return true;
+	return hasUseNodeDirective(fs.readFileSync(entryPoint, "utf8"));
+};
+const hasRuntimeProcedureType = (value) => value === "query" || value === "mutation" || value === "action";
+const getNativeHandlerExportNames = (source) => {
+	const exportNames = new Set(Array.from(source.matchAll(EXPORTED_NATIVE_HANDLER_CAPTURE_REGEX)).map((match) => match[1]).filter((name) => !!name));
+	const exportConstMatches = Array.from(source.matchAll(EXPORTED_CONST_CAPTURE_REGEX));
+	for (const [index, match] of exportConstMatches.entries()) {
+		const exportName = match[1];
+		if (!exportName) continue;
+		const start = (match.index ?? 0) + match[0].length;
+		const end = exportConstMatches[index + 1]?.index ?? source.length;
+		const initializerSlice = source.slice(start, end);
+		if (CHAINED_PROCEDURE_CAPTURE_REGEX.test(initializerSlice)) exportNames.add(exportName);
+	}
+	for (const match of source.matchAll(EXPORTED_ORM_API_DESTRUCTURE_CAPTURE_REGEX)) {
+		const bindings = match[1];
+		for (const binding of bindings.split(",")) {
+			const trimmed = binding.trim();
+			if (!trimmed || trimmed.startsWith("...")) continue;
+			const withoutDefault = trimmed.split("=")[0]?.trim() ?? "";
+			const localBinding = withoutDefault.split(":")[1]?.trim() ?? withoutDefault;
+			if (VALID_IDENTIFIER_REGEX.test(localBinding)) exportNames.add(localBinding);
+		}
+	}
+	return Array.from(exportNames);
+};
+const listConvexHandlerExports = async (entryPoint, jitiInstance) => {
+	const exportNames = /* @__PURE__ */ new Set();
+	const source = fs.readFileSync(entryPoint, "utf8");
+	for (const exportName of getNativeHandlerExportNames(source)) exportNames.add(exportName);
+	try {
+		const module = await jitiInstance.import(entryPoint);
+		if (module && typeof module === "object") for (const [name, value] of Object.entries(module)) {
+			if (name.startsWith("_")) continue;
+			const meta = value._crpcMeta;
+			if (hasRuntimeProcedureType(meta?.type)) exportNames.add(name);
+		}
+	} catch {}
+	return Array.from(exportNames).sort((a, b) => a.localeCompare(b));
+};
+const scanHandlerExportsByEntry = async (entryPoints) => {
+	const jitiInstance = createJiti(process.cwd(), {
+		interopDefault: true,
+		moduleCache: false
+	});
+	const results = await Promise.all(entryPoints.map(async (entryPoint) => ({
+		entryPoint,
+		exportNames: await listConvexHandlerExports(entryPoint, jitiInstance)
+	})));
+	const byEntry = /* @__PURE__ */ new Map();
+	for (const result of results) if (result.exportNames.length > 0) byEntry.set(result.entryPoint, result.exportNames);
+	return byEntry;
+};
+const parseArgs$1 = (argv) => {
+	const options = {
+		mode: "hotspot",
+		entryPattern: null,
+		details: false,
+		showInputs: false,
+		interactive: "never",
+		includeGenerated: false,
+		showSmall: false,
+		width: null,
+		topInputs: DEFAULT_TOP_INPUTS,
+		topPackages: DEFAULT_TOP_PACKAGES,
+		detailEntries: DEFAULT_DETAIL_ENTRIES,
+		warningMb: DEFAULT_WARNING_MB,
+		dangerMb: DEFAULT_DANGER_MB,
+		failMb: null
+	};
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (arg === "--hotspot") throw new Error("`--hotspot` was removed. Hotspot is the default mode, so just run `better-convex analyze`.");
+		if (arg === "--deploy") {
+			options.mode = "deploy";
+			continue;
+		}
+		if (arg === "--entry" || arg.startsWith("--entry=")) throw new Error("`--entry` was removed. Pass the entry regex as the first positional argument, e.g. `better-convex analyze polar.*`.");
+		if (arg === "--detail-entries" || arg.startsWith("--detail-entries=") || arg === "--top" || arg.startsWith("--top=")) throw new Error("`--top` and `--detail-entries` were removed. The analyzer now uses built-in detail defaults.");
+		if (arg === "--details") {
+			options.details = true;
+			continue;
+		}
+		if (arg === "--input") {
+			options.showInputs = true;
+			continue;
+		}
+		if (arg === "--interactive" || arg === "-i") {
+			options.interactive = "always";
+			continue;
+		}
+		if (arg === "--no-interactive" || arg === "-I") throw new Error("`--no-interactive` was removed. Non-interactive is already the default.");
+		if (arg === "--all" || arg === "-a") {
+			options.includeGenerated = true;
+			continue;
+		}
+		if (!arg.startsWith("-")) {
+			if (options.entryPattern !== null) throw new Error(`Only one positional entry regex is allowed. Received "${options.entryPattern}" and "${arg}".`);
+			options.entryPattern = arg;
+			continue;
+		}
+		if (arg === "--show-small") {
+			options.showSmall = true;
+			continue;
+		}
+		if (arg === "--width" && next) {
+			const parsed = Number.parseInt(next, 10);
+			if (Number.isFinite(parsed) && parsed >= 60) options.width = parsed;
+			i += 1;
+			continue;
+		}
+		if (arg === "--top-inputs" && next) {
+			const parsed = Number.parseInt(next, 10);
+			if (Number.isFinite(parsed) && parsed > 0) options.topInputs = parsed;
+			i += 1;
+			continue;
+		}
+		if (arg === "--top-packages" && next) {
+			const parsed = Number.parseInt(next, 10);
+			if (Number.isFinite(parsed) && parsed > 0) options.topPackages = parsed;
+			i += 1;
+			continue;
+		}
+		if (arg === "--warn-mb" && next) {
+			const parsed = Number.parseFloat(next);
+			if (Number.isFinite(parsed) && parsed > 0) options.warningMb = parsed;
+			i += 1;
+			continue;
+		}
+		if (arg === "--danger-mb" && next) {
+			const parsed = Number.parseFloat(next);
+			if (Number.isFinite(parsed) && parsed > 0) options.dangerMb = parsed;
+			i += 1;
+			continue;
+		}
+		if (arg === "--fail-mb" && next) {
+			const parsed = Number.parseFloat(next);
+			if (Number.isFinite(parsed) && parsed > 0) options.failMb = parsed;
+			i += 1;
+			continue;
+		}
+		if (arg === "--help" || arg === "-h") {
+			console.log(`Usage:
+  better-convex analyze [entryRegex]
+  better-convex analyze --deploy
+  better-convex analyze '^convex/functions/auth\\.ts$' --details
+
+Modes:
+  (default)            Hotspot analysis (per-function isolate ranking)
+  --deploy             Deploy analysis (single isolate bundle, Convex-like)
+
+Flags:
+  --details            Show extra per-entry/package details
+  --input              Include top internal inputs in detail output
+  --interactive, -i    Enable interactive hotspot UI (default: off, TTY only)
+  --all, -a           Include all Convex-ignored entries (multi-dot files + generated/, even without handlers)
+  --show-small         Include tiny dependencies (hidden by default)
+  --width <n>          Force output width (min 60)
+  --top-inputs <n>     Rows for input tables (default ${DEFAULT_TOP_INPUTS})
+  --top-packages <n>   Rows for package tables (default ${DEFAULT_TOP_PACKAGES})
+  --warn-mb <n>        WARN threshold per entry/chunk (default ${DEFAULT_WARNING_MB})
+  --danger-mb <n>      DANGER threshold per entry/chunk (default ${DEFAULT_DANGER_MB})
+  --fail-mb <n>        Exit 1 if largest entry/chunk >= n MB`);
+			process.exit(0);
+		}
+	}
+	if (options.mode === "deploy" && options.interactive === "always") throw new Error("`--interactive` is hotspot-only. Remove it when using `--deploy`.");
+	return options;
+};
+const schemaExternalFallbackPlugin = {
+	name: "schema-external-fallback",
+	setup(buildCtx) {
+		buildCtx.onResolve({ filter: SCHEMA_RESOLVE_FILTER }, (args) => ({
+			path: args.path,
+			external: true
+		}));
+	}
+};
+const shouldRetryWithSchemaExternalized = (error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.includes("No matching export") && (message.includes("schema.ts") || message.includes("/schema"));
+};
+const severityForBytes = (bytes, options) => {
+	const outputMb = bytes / MB;
+	if (outputMb >= options.dangerMb) return "DANGER";
+	if (outputMb >= options.warningMb) return "WARN";
+	return "OK";
+};
+const smallInputThreshold = (outputBytes) => Math.max(SMALL_INPUT_MIN_BYTES, Math.floor(outputBytes * SMALL_INPUT_MIN_SHARE));
+const isSmallInput = (bytesInOutput, outputBytes, showSmall) => !showSmall && bytesInOutput < smallInputThreshold(outputBytes);
+const shortPath = (inputPath) => {
+	if (inputPath.startsWith("convex/functions/")) return `fn/${inputPath.slice(17)}`;
+	if (inputPath.startsWith("convex/lib/")) return `lib/${inputPath.slice(11)}`;
+	if (inputPath.startsWith("../packages/better-convex/dist/")) return `bcx/${inputPath.slice(31)}`;
+	if (inputPath.startsWith("../node_modules/")) return `nm/${inputPath.slice(16)}`;
+	if (inputPath.startsWith("example/convex/")) return `convex/${inputPath.slice(15)}`;
+	return inputPath;
+};
+const compactPath = (inputPath, maxWidth) => truncate(shortPath(inputPath), Math.max(16, maxWidth));
+const isNodeModulesInputPath = (inputPath) => inputPath.includes("node_modules/");
+const packageFromInputPath = (inputPath) => {
+	const idx = inputPath.lastIndexOf("node_modules/");
+	if (idx >= 0) {
+		const [first, second] = inputPath.slice(idx + 13).split("/");
+		if (!first) return "(node_modules)";
+		if (first.startsWith("@") && second) return `${first}/${second}`;
+		return first;
+	}
+	if (inputPath.startsWith("convex/")) return "workspace:convex";
+	if (inputPath.startsWith("../packages/")) {
+		const parts = inputPath.replace("../", "").split("/");
+		return parts.length >= 2 ? `workspace:${parts[0]}/${parts[1]}` : "workspace:packages";
+	}
+	if (inputPath.startsWith("packages/")) {
+		const parts = inputPath.split("/");
+		return parts.length >= 2 ? `workspace:${parts[0]}/${parts[1]}` : "workspace:packages";
+	}
+	return "(other)";
+};
+const buildHotspotEntry = (entryPoint, externalizeSchema) => build({
+	bundle: true,
+	entryPoints: [entryPoint],
+	external: ["convex", "convex/*"],
+	format: "esm",
+	logLevel: "silent",
+	metafile: true,
+	platform: "browser",
+	target: ["esnext"],
+	conditions: ["convex", "module"],
+	minifySyntax: true,
+	minifyIdentifiers: true,
+	minifyWhitespace: false,
+	define: { "process.env.NODE_ENV": "\"production\"" },
+	write: false,
+	plugins: externalizeSchema ? [schemaExternalFallbackPlugin] : []
+});
+const analyzeHotspotEntry = async (entryPoint, projectRoot, includeDeepData) => {
+	let result;
+	let schemaExternalized = false;
+	try {
+		result = await buildHotspotEntry(entryPoint, false);
+	} catch (error) {
+		if (!shouldRetryWithSchemaExternalized(error)) throw error;
+		result = await buildHotspotEntry(entryPoint, true);
+		schemaExternalized = true;
+	}
+	const meta = result.metafile;
+	if (!meta) throw new Error(`No metafile generated for ${entryPoint}`);
+	const output = Object.values(meta.outputs).at(0);
+	if (!output) throw new Error(`No output generated for ${entryPoint}`);
+	const inputEntries = Object.entries(meta.inputs);
+	const totalInputBytes = inputEntries.reduce((sum, [, value]) => sum + (value.bytes ?? 0), 0);
+	const isLocalInput = (inputPath) => inputPath.startsWith("convex/") || inputPath.startsWith("example/convex/") || inputPath.includes("/example/convex/");
+	const localInputBytes = inputEntries.filter(([inputPath]) => isLocalInput(inputPath)).reduce((sum, [, value]) => sum + (value.bytes ?? 0), 0);
+	const row = {
+		entry: path.relative(projectRoot, entryPoint),
+		inputCount: inputEntries.length,
+		localInputBytes,
+		dependencyInputBytes: Math.max(0, totalInputBytes - localInputBytes),
+		totalInputBytes,
+		outputBytes: output.bytes,
+		schemaExternalized
+	};
+	if (!includeDeepData) return row;
+	const bytesByInput = new Map(inputEntries.map(([inputPath, value]) => [inputPath, value.bytes ?? 0]));
+	const outputInputs = Object.entries(output.inputs ?? {}).map(([inputPath, value]) => ({
+		path: inputPath,
+		bytesInOutput: value.bytesInOutput ?? 0,
+		sourceBytes: bytesByInput.get(inputPath) ?? 0
+	})).sort((a, b) => b.bytesInOutput - a.bytesInOutput);
+	const inputSet = new Set(inputEntries.map(([inputPath]) => inputPath));
+	const importsByInput = Object.fromEntries(inputEntries.map(([inputPath, value]) => [inputPath, Array.from(new Set((value.imports ?? []).map((entry) => entry.path).filter((importPath) => typeof importPath === "string" && inputSet.has(importPath))))]));
+	return {
+		...row,
+		deep: {
+			importsByInput,
+			outputInputs
+		}
+	};
+};
+const printHotspotTopInputs = (row, options) => {
+	if (!row.deep) return;
+	const internalInputs = row.deep.outputInputs.filter((input) => input.bytesInOutput > 0 && !isNodeModulesInputPath(input.path));
+	const externalBytes = row.deep.outputInputs.filter((input) => input.bytesInOutput > 0 && isNodeModulesInputPath(input.path)).reduce((sum, input) => sum + input.bytesInOutput, 0);
+	const topInputs = internalInputs.filter((input) => !isSmallInput(input.bytesInOutput, row.outputBytes, options.showSmall)).slice(0, options.topInputs);
+	const hiddenInputs = internalInputs.filter((input) => isSmallInput(input.bytesInOutput, row.outputBytes, options.showSmall));
+	const hiddenBytes = hiddenInputs.reduce((sum, input) => sum + input.bytesInOutput, 0);
+	if (topInputs.length === 0) {
+		if (!options.showSmall && hiddenInputs.length > 0) {
+			console.log("");
+			console.log(bold(`Top internal inputs: ${row.entry}`));
+			console.log(dim(`(all visible internal inputs were small; hidden ${hiddenInputs.length} inputs / ${toMB(hiddenBytes)} MB)`));
+			if (externalBytes > 0) console.log(dim(`External deps are summarized in Top packages (${toMB(externalBytes)} MB).`));
+		}
+		return;
+	}
+	console.log("");
+	console.log(bold(`Top internal inputs: ${row.entry}`));
+	const inputPathWidth = Math.max(18, outputWidth - 57);
+	console.log(dim(`bytesInOutput  sourceBytes    share       impact  ${pad("path", inputPathWidth)}`));
+	console.log(dim(`-------------  ----------  ----------  ----------------  ${"-".repeat(inputPathWidth)}`));
+	for (const input of topInputs) {
+		const share = row.outputBytes > 0 ? input.bytesInOutput / row.outputBytes * 100 : 0;
+		const bytesInOutput = input.bytesInOutput.toString().padStart(13);
+		const sourceBytes = input.sourceBytes.toString().padStart(10);
+		const sharePct = colorize(`${share.toFixed(2)}%`.padStart(10), shareColor(share));
+		const bar = makeShareBar(share);
+		console.log(`${bytesInOutput}  ${sourceBytes}  ${sharePct}  ${bar}  ${compactPath(input.path, inputPathWidth)}`);
+	}
+	if (!options.showSmall && hiddenInputs.length > 0) {
+		const share = row.outputBytes > 0 ? hiddenBytes / row.outputBytes * 100 : 0;
+		const hiddenLabel = dim(`(small: ${hiddenInputs.length} hidden inputs)`);
+		console.log(`${hiddenBytes.toString().padStart(13)}  ${"".padStart(10)}  ${colorize(`${share.toFixed(2)}%`.padStart(10), ANSI.gray)}  ${makeShareBar(share)}  ${hiddenLabel}`);
+	}
+	if (externalBytes > 0) {
+		const share = row.outputBytes > 0 ? externalBytes / row.outputBytes * 100 : 0;
+		console.log(dim(`External deps: ${toMB(externalBytes)} MB (${share.toFixed(2)}%), see Top packages.`));
+	}
+};
+const printHotspotPackages = (row, options) => {
+	if (!row.deep) return;
+	const packageRows = buildPackageImportGraphRows(row, Number.POSITIVE_INFINITY);
+	const visibleRows = packageRows.filter((item) => !isSmallInput(item.bytesInOutput, row.outputBytes, options.showSmall));
+	const hiddenRows = packageRows.filter((item) => isSmallInput(item.bytesInOutput, row.outputBytes, options.showSmall));
+	const hiddenBytes = hiddenRows.reduce((sum, item) => sum + item.bytesInOutput, 0);
+	const topRows = visibleRows.slice(0, options.topPackages);
+	console.log("");
+	console.log(bold(`Package graph: ${row.entry}`));
+	if (topRows.length === 0) {
+		console.log("  (no packages above small-dependency threshold)");
+		return;
+	}
+	const packageColWidth = Math.max(16, Math.min(30, outputWidth - 58));
+	const barWidth = Math.max(8, Math.min(16, outputWidth - (packageColWidth + 52)));
+	for (const [index, item] of topRows.entries()) {
+		const share = row.outputBytes > 0 ? item.bytesInOutput / row.outputBytes * 100 : 0;
+		const shareStr = colorize(`${share.toFixed(2)}%`, shareColor(share));
+		const sizeStr = colorize(`${toMB(item.bytesInOutput)} MB`, shareColor(share));
+		const bar = makeShareBar(share, barWidth);
+		const packageLabel = truncate(item.packageName, packageColWidth);
+		const targetPrefix = dim("   imports -> ");
+		const maxTargetWidth = Math.max(18, outputWidth - visibleLength(targetPrefix) - 2);
+		console.log(`${bold(`${index + 1}.`)} ${pad(packageLabel, packageColWidth)} ${pad(sizeStr, 18)} ${pad(shareStr, 10)} ${bar}`);
+		if (item.topTargets.length > 0) {
+			const targetLabel = item.topTargets.join(", ");
+			console.log(`${targetPrefix}${truncate(targetLabel, maxTargetWidth)}`);
+		}
+	}
+	if (!options.showSmall && hiddenRows.length > 0) {
+		const share = row.outputBytes > 0 ? hiddenBytes / row.outputBytes * 100 : 0;
+		console.log(`   ${dim(`(small packages hidden: ${hiddenRows.length}, ${toMB(hiddenBytes)} MB, ${share.toFixed(2)}%)`)}`);
+	}
+};
+const shouldPromptForHotspotPick = (options) => {
+	if (options.interactive === "never") return false;
+	if (!isInteractiveTerminal) return false;
+	if (options.details || options.entryPattern) return false;
+	return options.interactive === "always";
+};
+const HOTSPOT_SORT_ORDER = [
+	"out",
+	"dep",
+	"fns"
+];
+const HOTSPOT_DETAIL_ORDER = [
+	"handlers",
+	"packages",
+	"inputs"
+];
+const HOTSPOT_MIN_SPLIT_COLUMNS = 120;
+const HOTSPOT_LEFT_MIN_WIDTH = 30;
+const HOTSPOT_LEFT_MAX_WIDTH = 56;
+const HOTSPOT_HEADER_LINES = 2;
+const HOTSPOT_BOTTOM_LINES = 2;
+const clampNumber = (value, min, max) => Math.min(Math.max(value, min), max);
+const cycleHotspotSort = (sortKey) => {
+	return HOTSPOT_SORT_ORDER[(HOTSPOT_SORT_ORDER.indexOf(sortKey) + 1) % HOTSPOT_SORT_ORDER.length];
+};
+const cycleHotspotDetailPane = (detailPane) => {
+	return HOTSPOT_DETAIL_ORDER[(HOTSPOT_DETAIL_ORDER.indexOf(detailPane) + 1) % HOTSPOT_DETAIL_ORDER.length];
+};
+const cycleHotspotDetailPaneBackward = (detailPane) => {
+	return HOTSPOT_DETAIL_ORDER[(HOTSPOT_DETAIL_ORDER.indexOf(detailPane) - 1 + HOTSPOT_DETAIL_ORDER.length) % HOTSPOT_DETAIL_ORDER.length];
+};
+const fitListViewport = (totalRows, selectedIndex, viewportHeight, topIndex) => {
+	if (totalRows <= 0 || viewportHeight <= 0) return 0;
+	const maxTop = Math.max(0, totalRows - viewportHeight);
+	const clampedSelected = clampNumber(selectedIndex, 0, totalRows - 1);
+	let nextTop = clampNumber(topIndex, 0, maxTop);
+	if (clampedSelected < nextTop) nextTop = clampedSelected;
+	else if (clampedSelected >= nextTop + viewportHeight) nextTop = clampedSelected - viewportHeight + 1;
+	return clampNumber(nextTop, 0, maxTop);
+};
+const pickSelectedIndex = (rows, preferredEntry, fallbackIndex) => {
+	if (rows.length === 0) return 0;
+	if (preferredEntry) {
+		const preferredIndex = rows.findIndex((row) => row.entry === preferredEntry);
+		if (preferredIndex >= 0) return preferredIndex;
+	}
+	return clampNumber(fallbackIndex, 0, rows.length - 1);
+};
+const resolveInteractiveLayout = (columns, rows) => {
+	const safeColumns = Math.max(60, columns);
+	const safeRows = Math.max(12, rows);
+	const bodyHeight = Math.max(6, safeRows - HOTSPOT_HEADER_LINES - HOTSPOT_BOTTOM_LINES);
+	if (safeColumns >= HOTSPOT_MIN_SPLIT_COLUMNS) {
+		const leftWidth = clampNumber(Math.floor(safeColumns * .33), HOTSPOT_LEFT_MIN_WIDTH, HOTSPOT_LEFT_MAX_WIDTH);
+		const rightWidth = Math.max(24, safeColumns - leftWidth - 3);
+		const viewportHeight = Math.max(1, bodyHeight - 1);
+		return {
+			mode: "split",
+			columns: safeColumns,
+			rows: safeRows,
+			bodyHeight,
+			leftWidth,
+			rightWidth,
+			listViewportHeight: viewportHeight,
+			detailViewportHeight: viewportHeight
+		};
+	}
+	const stackBody = Math.max(5, bodyHeight);
+	const listHeight = Math.max(2, Math.floor((stackBody - 1) * .45));
+	let detailHeight = Math.max(2, stackBody - listHeight - 1);
+	if (listHeight + detailHeight + 1 > stackBody) detailHeight = Math.max(2, stackBody - listHeight - 1);
+	return {
+		mode: "stacked",
+		columns: safeColumns,
+		rows: safeRows,
+		bodyHeight: stackBody,
+		listHeight,
+		detailHeight,
+		listViewportHeight: Math.max(1, listHeight - 1),
+		detailViewportHeight: Math.max(1, detailHeight - 1)
+	};
+};
+const reduceInteractiveState = (state, action) => {
+	switch (action.type) {
+		case "moveSelection": {
+			if (action.rowCount <= 0) return {
+				...state,
+				selectedIndex: 0,
+				topIndex: 0
+			};
+			const nextIndex = clampNumber(state.selectedIndex + action.delta, 0, action.rowCount - 1);
+			return {
+				...state,
+				selectedIndex: nextIndex
+			};
+		}
+		case "setFilter": return {
+			...state,
+			filterQuery: action.query
+		};
+		case "cycleSort": return {
+			...state,
+			sortKey: cycleHotspotSort(state.sortKey)
+		};
+		case "cyclePane": return {
+			...state,
+			detailPane: action.direction === 1 ? cycleHotspotDetailPane(state.detailPane) : cycleHotspotDetailPaneBackward(state.detailPane)
+		};
+		case "toggleGenerated": return {
+			...state,
+			includeGenerated: !state.includeGenerated
+		};
+		case "toggleWatch": return {
+			...state,
+			watchEnabled: !state.watchEnabled
+		};
+		case "toggleHelp": return {
+			...state,
+			showHelp: !state.showHelp
+		};
+		case "requestRefresh": return {
+			...state,
+			statusMessage: "Refreshing analysis..."
+		};
+		case "setStatus": return {
+			...state,
+			statusMessage: action.message
+		};
+		case "setTopIndex": return {
+			...state,
+			topIndex: action.topIndex
+		};
+		default: return state;
+	}
+};
+const sortHotspotRows = (rows, sortKey) => {
+	const clone = [...rows];
+	if (sortKey === "dep") {
+		clone.sort((a, b) => b.dependencyInputBytes - a.dependencyInputBytes);
+		return clone;
+	}
+	if (sortKey === "fns") {
+		clone.sort((a, b) => b.handlerExports.length - a.handlerExports.length);
+		return clone;
+	}
+	clone.sort((a, b) => b.outputBytes - a.outputBytes);
+	return clone;
+};
+const filterHotspotRows = (rows, query) => {
+	const trimmed = query.trim().toLowerCase();
+	if (!trimmed) return rows;
+	return rows.filter((row) => {
+		if (row.entry.toLowerCase().includes(trimmed)) return true;
+		return row.handlerExports.some((name) => name.toLowerCase().includes(trimmed));
+	});
+};
+const sortLabel = (sortKey) => {
+	if (sortKey === "dep") return "DepMB";
+	if (sortKey === "fns") return "Fns";
+	return "OutMB";
+};
+const selectHotspotEntryPoints = (params) => {
+	const { baseCandidateEntries, allCandidateEntries, handlerExportsByEntry, includeGenerated } = params;
+	const isolateEntries = baseCandidateEntries.filter((entryPoint) => handlerExportsByEntry.has(entryPoint));
+	const baseEntrySet = new Set(baseCandidateEntries);
+	const ignoredEntries = allCandidateEntries.filter((entryPoint) => !baseEntrySet.has(entryPoint));
+	const generatedEntries = includeGenerated ? ignoredEntries : ignoredEntries.filter((entryPoint) => handlerExportsByEntry.has(entryPoint));
+	return {
+		isolateEntries,
+		generatedEntries,
+		entryPoints: dedupe([...isolateEntries, ...generatedEntries])
+	};
+};
+const filterEntryPointsByPattern = (entryPoints, roots, entryPattern) => {
+	if (!entryPattern) return entryPoints;
+	let regex;
+	try {
+		regex = new RegExp(entryPattern, "i");
+	} catch (error) {
+		const reason = error instanceof Error ? firstLine(error.message) : "invalid regex";
+		throw new Error(`Invalid entry regex "${entryPattern}": ${reason}`);
+	}
+	return entryPoints.filter((entryPoint) => regex.test(path.relative(roots.projectRoot, entryPoint)));
+};
+const collectAnalyzeEntrySelection = async (roots, options) => {
+	const allCandidateWithNode = walkDeployEntryPoints(roots.functionsRoot, {
+		includeMultiDot: true,
+		includeGeneratedDir: true
+	});
+	const nodeEntryPoints = allCandidateWithNode.filter((entryPoint) => isNodeEntryPoint(entryPoint, roots.functionsRoot));
+	const nodeEntrySet = new Set(nodeEntryPoints);
+	const allCandidateEntries = allCandidateWithNode.filter((entryPoint) => !nodeEntrySet.has(entryPoint));
+	const baseCandidateEntries = walkDeployEntryPoints(roots.functionsRoot).filter((entryPoint) => !nodeEntrySet.has(entryPoint));
+	const handlerExportsByEntry = await scanHandlerExportsByEntry(allCandidateEntries);
+	const { isolateEntries, generatedEntries, entryPoints } = selectHotspotEntryPoints({
+		baseCandidateEntries,
+		allCandidateEntries,
+		handlerExportsByEntry,
+		includeGenerated: options.includeGenerated
+	});
+	return {
+		nodeEntryPoints,
+		isolateEntries,
+		generatedEntries,
+		entryPoints: filterEntryPointsByPattern(entryPoints, roots, options.entryPattern),
+		handlerExportsByEntry
+	};
+};
+const collectHotspotRows = async (roots, options, includeDeepData) => {
+	const { isolateEntries, generatedEntries, entryPoints, handlerExportsByEntry } = await collectAnalyzeEntrySelection(roots, options);
+	const rows = [];
+	for (const entryPoint of entryPoints) try {
+		rows.push({
+			...await analyzeHotspotEntry(entryPoint, roots.projectRoot, includeDeepData),
+			handlerExports: handlerExportsByEntry.get(entryPoint) ?? []
+		});
+	} catch (error) {
+		rows.push({
+			entry: path.relative(roots.projectRoot, entryPoint),
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return {
+		isolateEntries,
+		generatedEntries,
+		entryPoints,
+		successRows: rows.filter((row) => !("error" in row)).sort((a, b) => b.outputBytes - a.outputBytes),
+		failedRows: rows.filter((row) => "error" in row),
+		handlerExportsByEntry
+	};
+};
+const buildPackageImportGraphRows = (row, limit = 12) => {
+	if (!row.deep) return [];
+	const packageBytes = /* @__PURE__ */ new Map();
+	const packageTargets = /* @__PURE__ */ new Map();
+	for (const input of row.deep.outputInputs) {
+		if (input.bytesInOutput <= 0) continue;
+		const sourcePackage = packageFromInputPath(input.path);
+		packageBytes.set(sourcePackage, (packageBytes.get(sourcePackage) ?? 0) + input.bytesInOutput);
+		const targets = row.deep.importsByInput[input.path] ?? [];
+		if (targets.length === 0) continue;
+		const targetCounts = packageTargets.get(sourcePackage) ?? /* @__PURE__ */ new Map();
+		for (const targetPath of targets) {
+			const targetPackage = packageFromInputPath(targetPath);
+			if (targetPackage === sourcePackage) continue;
+			targetCounts.set(targetPackage, (targetCounts.get(targetPackage) ?? 0) + 1);
+		}
+		packageTargets.set(sourcePackage, targetCounts);
+	}
+	const sorted = Array.from(packageBytes.entries()).map(([packageName, bytesInOutput]) => {
+		const targetMap = packageTargets.get(packageName) ?? /* @__PURE__ */ new Map();
+		return {
+			packageName,
+			bytesInOutput,
+			topTargets: Array.from(targetMap.entries()).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 3).map(([target]) => target)
+		};
+	}).sort((a, b) => b.bytesInOutput - a.bytesInOutput);
+	if (!Number.isFinite(limit)) return sorted;
+	return sorted.slice(0, limit);
+};
+const padVisible = (value, width) => {
+	const missing = width - visibleLength(value);
+	if (missing <= 0) return value;
+	return `${value}${" ".repeat(missing)}`;
+};
+const fillPane = (lines, height) => {
+	const next = [...lines];
+	while (next.length < height) next.push("");
+	return next.slice(0, height);
+};
+const buildHandlersPaneLines = (row, width) => {
+	if (!row) return [dim("No selected entry.")];
+	if (row.handlerExports.length === 0) return [dim("No handler exports detected.")];
+	return row.handlerExports.map((name) => `- ${truncate(name, width - 2)}`);
+};
+const buildPackagesPaneLines = (row, options, width) => {
+	if (!row) return [dim("No selected entry.")];
+	if (!row.deep) return [dim("No package data loaded.")];
+	const packageRows = buildPackageImportGraphRows(row, Number.POSITIVE_INFINITY);
+	const visibleRows = packageRows.filter((item) => !isSmallInput(item.bytesInOutput, row.outputBytes, options.showSmall));
+	const hiddenCount = packageRows.length - visibleRows.length;
+	const lines = [];
+	if (visibleRows.length === 0) {
+		lines.push(dim("No package rows above small-input threshold."));
+		return lines;
+	}
+	const topRows = visibleRows.slice(0, Math.min(12, options.topPackages));
+	const packageWidth = Math.max(10, width - 26);
+	for (const [index, pkg] of topRows.entries()) {
+		const share = row.outputBytes > 0 ? pkg.bytesInOutput / row.outputBytes * 100 : 0;
+		lines.push(`${pad(String(index + 1), 2, "right")} ${pad(truncate(pkg.packageName, packageWidth), packageWidth)} ${pad(`${toMB(pkg.bytesInOutput)}MB`, 9, "right")} ${pad(`${share.toFixed(2)}%`, 8, "right")}`);
+		if (pkg.topTargets.length > 0) {
+			const targetLabel = pkg.topTargets.join(", ");
+			lines.push(dim(`   -> ${truncate(targetLabel, Math.max(12, width - 7))}`));
+		}
+	}
+	if (!options.showSmall && hiddenCount > 0) lines.push(dim(`hidden small packages: ${hiddenCount}`));
+	return lines;
+};
+const buildInputsPaneLines = (row, options, width) => {
+	if (!row) return [dim("No selected entry.")];
+	if (!row.deep) return [dim("No input data loaded.")];
+	const internal = row.deep.outputInputs.filter((input) => input.bytesInOutput > 0 && !isNodeModulesInputPath(input.path));
+	const externalBytes = row.deep.outputInputs.filter((input) => input.bytesInOutput > 0 && isNodeModulesInputPath(input.path)).reduce((sum, input) => sum + input.bytesInOutput, 0);
+	const visibleInputs = internal.filter((input) => !isSmallInput(input.bytesInOutput, row.outputBytes, options.showSmall)).slice(0, Math.min(12, options.topInputs));
+	if (visibleInputs.length === 0) {
+		const lines = [dim("No internal inputs above small-input threshold.")];
+		if (externalBytes > 0) {
+			const share = row.outputBytes > 0 ? externalBytes / row.outputBytes * 100 : 0;
+			lines.push(dim(`external deps: ${toMB(externalBytes)}MB (${share.toFixed(2)}%)`));
+		}
+		return lines;
+	}
+	const pathWidth = Math.max(12, width - 24);
+	const lines = visibleInputs.map((input) => {
+		const share = row.outputBytes > 0 ? input.bytesInOutput / row.outputBytes * 100 : 0;
+		return `${pad(`${toMB(input.bytesInOutput)}MB`, 9, "right")} ${pad(`${share.toFixed(2)}%`, 8, "right")} ${truncate(shortPath(input.path), pathWidth)}`;
+	});
+	if (externalBytes > 0) {
+		const share = row.outputBytes > 0 ? externalBytes / row.outputBytes * 100 : 0;
+		lines.push(dim(`external deps: ${toMB(externalBytes)}MB (${share.toFixed(2)}%)`));
+	}
+	return lines;
+};
+const buildHelpPaneLines = () => [
+	"j/k move selection",
+	"left/right arrow cycle detail pane",
+	"/ filter entries",
+	"s sort cycle (OutMB, DepMB, Fns)",
+	"g toggle all entries",
+	"r refresh analysis",
+	"w toggle watch mode",
+	"? toggle help overlay",
+	"q quit"
+];
+const runHotspotInteractive = async (roots, options) => {
+	const stdin = process.stdin;
+	const stdout = process.stdout;
+	let state = {
+		selectedIndex: 0,
+		topIndex: 0,
+		filterQuery: "",
+		sortKey: "out",
+		detailPane: "packages",
+		includeGenerated: options.includeGenerated,
+		watchEnabled: false,
+		showHelp: false,
+		statusMessage: ""
+	};
+	let snapshot = await collectHotspotRows(roots, {
+		...options,
+		includeGenerated: state.includeGenerated,
+		entryPattern: null
+	}, false);
+	let visibleRows = sortHotspotRows(filterHotspotRows(snapshot.successRows, state.filterQuery), state.sortKey);
+	let watcher = null;
+	let watchTimer = null;
+	let refreshing = false;
+	let refreshQueued = false;
+	let shouldQuit = false;
+	let listViewportHeight = 10;
+	const deepRowCache = /* @__PURE__ */ new Map();
+	const getSelectedEntry = () => visibleRows.at(state.selectedIndex)?.entry ?? null;
+	const findRowByEntry = (entry) => {
+		if (!entry) return null;
+		return snapshot.successRows.find((row) => row.entry === entry) ?? null;
+	};
+	const syncVisibleRows = (preferredEntry) => {
+		visibleRows = sortHotspotRows(filterHotspotRows(snapshot.successRows, state.filterQuery), state.sortKey);
+		const nextSelectedIndex = pickSelectedIndex(visibleRows, preferredEntry, state.selectedIndex);
+		const nextTopIndex = fitListViewport(visibleRows.length, nextSelectedIndex, listViewportHeight, state.topIndex);
+		state = reduceInteractiveState(state, {
+			type: "setTopIndex",
+			topIndex: nextTopIndex
+		});
+		state = {
+			...state,
+			selectedIndex: nextSelectedIndex
+		};
+	};
+	const refreshSnapshot = async (reason) => {
+		if (refreshing) {
+			refreshQueued = true;
+			return;
+		}
+		refreshing = true;
+		state = reduceInteractiveState(state, {
+			type: "setStatus",
+			message: reason
+		});
+		const preferredEntry = getSelectedEntry();
+		try {
+			snapshot = await collectHotspotRows(roots, {
+				...options,
+				includeGenerated: state.includeGenerated,
+				entryPattern: null
+			}, false);
+			deepRowCache.clear();
+			syncVisibleRows(preferredEntry);
+			state = reduceInteractiveState(state, {
+				type: "setStatus",
+				message: `Refreshed (${snapshot.successRows.length} entries).`
+			});
+		} catch (error) {
+			state = reduceInteractiveState(state, {
+				type: "setStatus",
+				message: `Refresh failed: ${firstLine(error instanceof Error ? error.message : String(error))}`
+			});
+		} finally {
+			refreshing = false;
+			if (refreshQueued) {
+				refreshQueued = false;
+				await refreshSnapshot("Refreshing (queued)...");
+			}
+		}
+	};
+	const stopWatcher = () => {
+		if (watcher) {
+			watcher.close();
+			watcher = null;
+		}
+		if (watchTimer) {
+			clearTimeout(watchTimer);
+			watchTimer = null;
+		}
+	};
+	const applyWatchMode = () => {
+		if (!state.watchEnabled) {
+			stopWatcher();
+			state = reduceInteractiveState(state, {
+				type: "setStatus",
+				message: "Watch mode disabled."
+			});
+			return;
+		}
+		try {
+			watcher = fs.watch(roots.functionsRoot, { recursive: true }, () => {
+				if (watchTimer) clearTimeout(watchTimer);
+				watchTimer = setTimeout(() => {
+					refreshSnapshot("Auto-refresh (file change)...");
+				}, 200);
+			});
+			state = reduceInteractiveState(state, {
+				type: "setStatus",
+				message: "Watch mode enabled."
+			});
+		} catch (error) {
+			state = reduceInteractiveState(state, { type: "toggleWatch" });
+			state = reduceInteractiveState(state, {
+				type: "setStatus",
+				message: `Watch unavailable: ${firstLine(error instanceof Error ? error.message : String(error))}`
+			});
+		}
+	};
+	const promptFilter = async () => {
+		if (typeof stdin.setRawMode === "function") stdin.setRawMode(false);
+		const rl = createInterface({
+			input: stdin,
+			output: stdout
+		});
+		try {
+			const value = await rl.question("Filter entries (empty clears): ");
+			const preferredEntry = getSelectedEntry();
+			state = reduceInteractiveState(state, {
+				type: "setFilter",
+				query: value.trim()
+			});
+			syncVisibleRows(preferredEntry);
+			state = reduceInteractiveState(state, {
+				type: "setStatus",
+				message: state.filterQuery ? `Filter applied: "${state.filterQuery}"` : "Filter cleared."
+			});
+		} finally {
+			rl.close();
+			if (typeof stdin.setRawMode === "function") stdin.setRawMode(true);
+			stdin.resume();
+			stdin.setEncoding("utf8");
+		}
+	};
+	const ensureDeepRow = async (entry) => {
+		if (deepRowCache.has(entry)) return deepRowCache.get(entry) ?? null;
+		const entryPoint = path.join(roots.projectRoot, entry);
+		try {
+			const analyzed = await analyzeHotspotEntry(entryPoint, roots.projectRoot, true);
+			const fallbackHandlers = findRowByEntry(entry)?.handlerExports ?? [];
+			const mergedRow = {
+				...analyzed,
+				handlerExports: snapshot.handlerExportsByEntry.get(entryPoint) ?? fallbackHandlers
+			};
+			deepRowCache.set(entry, mergedRow);
+			return mergedRow;
+		} catch (error) {
+			deepRowCache.set(entry, null);
+			state = reduceInteractiveState(state, {
+				type: "setStatus",
+				message: `Detail load failed for ${entry}: ${firstLine(error instanceof Error ? error.message : String(error))}`
+			});
+			return null;
+		}
+	};
+	const renderInteractive = async () => {
+		const layout = resolveInteractiveLayout(stdout.columns ?? outputWidth, stdout.rows ?? 30);
+		listViewportHeight = layout.listViewportHeight;
+		state = reduceInteractiveState(state, {
+			type: "setTopIndex",
+			topIndex: fitListViewport(visibleRows.length, state.selectedIndex, layout.listViewportHeight, state.topIndex)
+		});
+		const activeEntry = (visibleRows.at(state.selectedIndex) ?? null)?.entry ?? null;
+		let detailRow = findRowByEntry(activeEntry);
+		if (!state.showHelp && activeEntry && state.detailPane !== "handlers") detailRow = await ensureDeepRow(activeEntry);
+		const statusLine = state.statusMessage || "Ready";
+		const headerLine = `entries=${visibleRows.length}/${snapshot.successRows.length} sort=${sortLabel(state.sortKey)} filter=${state.filterQuery || "∅"} all=${state.includeGenerated ? "on" : "off"} pane=${state.detailPane} watch=${state.watchEnabled ? "on" : "off"}`;
+		const listLines = (() => {
+			const lines = [bold(truncate(`Entries (${visibleRows.length})${state.filterQuery ? ` · filter="${state.filterQuery}"` : ""}`, layout.mode === "split" ? layout.leftWidth : layout.columns))];
+			if (visibleRows.length === 0) lines.push(dim("No entries. Adjust filter or refresh."));
+			else {
+				const start = state.topIndex;
+				const end = Math.min(visibleRows.length, start + layout.listViewportHeight);
+				const labelWidth = (layout.mode === "split" ? layout.leftWidth : layout.columns) - 4;
+				for (let i = start; i < end; i += 1) {
+					const row = visibleRows[i];
+					const marker = i === state.selectedIndex ? colorize("›", ANSI.cyan) : " ";
+					const label = truncate(`${row.entry} · ${toMB(row.outputBytes)}MB · ${row.handlerExports.length} fn`, Math.max(16, labelWidth));
+					lines.push(`${marker} ${label}`);
+				}
+			}
+			return lines;
+		})();
+		const detailTitle = `Detail (${state.detailPane}) · ${state.showHelp ? "help" : activeEntry ? activeEntry : "none"}`;
+		const detailBodyWidth = (layout.mode === "split" ? layout.rightWidth : layout.columns) - 1;
+		const detailBody = state.showHelp ? buildHelpPaneLines() : state.detailPane === "handlers" ? buildHandlersPaneLines(detailRow, detailBodyWidth) : state.detailPane === "packages" ? buildPackagesPaneLines(detailRow, options, detailBodyWidth) : buildInputsPaneLines(detailRow, options, detailBodyWidth);
+		const detailLines = [bold(truncate(detailTitle, detailBodyWidth)), ...detailBody];
+		const keyHints = "j/k move  ←/→ pane  / filter  s sort  g all  r refresh  w watch  ? help  q quit";
+		stdout.write("\x1B[2J\x1B[H");
+		console.log(bold("better-convex analyze · interactive"));
+		console.log(dim(truncate(headerLine, layout.columns)));
+		if (layout.mode === "split") {
+			const leftPane = fillPane(listLines, layout.bodyHeight);
+			const rightPane = fillPane(detailLines, layout.bodyHeight);
+			for (let i = 0; i < layout.bodyHeight; i += 1) {
+				const left = padVisible(truncate(leftPane[i] ?? "", layout.leftWidth), layout.leftWidth);
+				const right = truncate(rightPane[i] ?? "", layout.rightWidth);
+				console.log(`${left} │ ${right}`);
+			}
+		} else {
+			const listPane = fillPane(listLines, layout.listHeight);
+			const detailPane = fillPane(detailLines, layout.detailHeight);
+			for (const line of listPane) console.log(truncate(line, layout.columns));
+			console.log(dim("-".repeat(layout.columns)));
+			for (const line of detailPane) console.log(truncate(line, layout.columns));
+		}
+		console.log(dim(truncate(keyHints, layout.columns)));
+		console.log(dim(truncate(statusLine, layout.columns)));
+	};
+	const readKey = () => new Promise((resolve) => {
+		stdin.once("data", (data) => resolve(String(data)));
+	});
+	syncVisibleRows(null);
+	if (typeof stdin.setRawMode === "function") stdin.setRawMode(true);
+	stdin.resume();
+	stdin.setEncoding("utf8");
+	try {
+		while (!shouldQuit) {
+			await renderInteractive();
+			const key = await readKey();
+			if (key === "" || key === "q") {
+				shouldQuit = true;
+				continue;
+			}
+			if (key === "j" || key === "\x1B[B") {
+				state = reduceInteractiveState(state, {
+					type: "moveSelection",
+					delta: 1,
+					rowCount: visibleRows.length
+				});
+				continue;
+			}
+			if (key === "k" || key === "\x1B[A") {
+				state = reduceInteractiveState(state, {
+					type: "moveSelection",
+					delta: -1,
+					rowCount: visibleRows.length
+				});
+				continue;
+			}
+			if (key === "/") {
+				await promptFilter();
+				continue;
+			}
+			if (key === "s") {
+				const preferredEntry = getSelectedEntry();
+				state = reduceInteractiveState(state, { type: "cycleSort" });
+				syncVisibleRows(preferredEntry);
+				state = reduceInteractiveState(state, {
+					type: "setStatus",
+					message: `Sort: ${sortLabel(state.sortKey)}`
+				});
+				continue;
+			}
+			if (key === "g") {
+				state = reduceInteractiveState(state, { type: "toggleGenerated" });
+				await refreshSnapshot(state.includeGenerated ? "Refreshing with all entries..." : "Refreshing with function entries only...");
+				continue;
+			}
+			if (key === "\x1B[C") {
+				state = reduceInteractiveState(state, {
+					type: "cyclePane",
+					direction: 1
+				});
+				state = reduceInteractiveState(state, {
+					type: "setStatus",
+					message: `Detail pane: ${state.detailPane}`
+				});
+				continue;
+			}
+			if (key === "\x1B[D") {
+				state = reduceInteractiveState(state, {
+					type: "cyclePane",
+					direction: -1
+				});
+				state = reduceInteractiveState(state, {
+					type: "setStatus",
+					message: `Detail pane: ${state.detailPane}`
+				});
+				continue;
+			}
+			if (key === "r") {
+				state = reduceInteractiveState(state, { type: "requestRefresh" });
+				await refreshSnapshot(state.statusMessage);
+				continue;
+			}
+			if (key === "w") {
+				state = reduceInteractiveState(state, { type: "toggleWatch" });
+				applyWatchMode();
+				continue;
+			}
+			if (key === "?") state = reduceInteractiveState(state, { type: "toggleHelp" });
+		}
+	} finally {
+		stopWatcher();
+		if (typeof stdin.setRawMode === "function") stdin.setRawMode(false);
+		stdin.pause();
+		stdout.write("\x1B[2J\x1B[H");
+	}
+	return 0;
+};
+const runHotspotAnalysis = async (roots, options) => {
+	if (shouldPromptForHotspotPick(options)) return runHotspotInteractive(roots, options);
+	const includeDeepData = options.details;
+	const { isolateEntries, generatedEntries, entryPoints, successRows, failedRows } = await collectHotspotRows(roots, options, includeDeepData);
+	if (entryPoints.length === 0) {
+		if (options.includeGenerated) console.log("No matching entries found for the provided regex.");
+		else console.log("No matching Convex handler entries found (files exporting query/mutation/action, including internal variants).");
+		return 0;
+	}
+	const outputTotal = successRows.reduce((sum, row) => sum + row.outputBytes, 0);
+	const outputAverage = successRows.length > 0 ? outputTotal / successRows.length : 0;
+	const totalHandlers = successRows.reduce((sum, row) => sum + row.handlerExports.length, 0);
+	const largest = successRows.at(0);
+	const buildHotspotDetailCommand = (entry, mode) => {
+		const parts = [
+			"better-convex",
+			"analyze",
+			shellQuote(`^${escapeRegex(entry)}$`),
+			"--details"
+		];
+		if (options.showInputs) parts.push("--input");
+		if (options.includeGenerated) parts.push("--all");
+		if (options.detailEntries !== DEFAULT_DETAIL_ENTRIES) parts.push("--top", String(options.detailEntries));
+		if (mode === "agent") parts.push("--top-inputs", "30", "--top-packages", "20");
+		return parts.join(" ");
+	};
+	const actionRows = successRows;
+	console.log(bold("Runtime hotspot analysis (least optimized functions)"));
+	console.log(`isolateEntries=${isolateEntries.length} handlers=${totalHandlers} extraAll=${generatedEntries.length} selected=${entryPoints.length} ok=${successRows.length} failed=${failedRows.length} avg=${formatBytes(outputAverage)}${largest ? ` largest=${largest.entry} (${formatBytes(largest.outputBytes)})` : ""}`);
+	console.log("");
+	if (actionRows.length > 0) {
+		console.log(bold("Agent queue (run top-down):"));
+		for (const [index, row] of actionRows.entries()) console.log(`${index + 1}. ${row.entry} (${toMB(row.outputBytes)} MB, ${row.handlerExports.length} handlers) -> ${buildHotspotDetailCommand(row.entry, "agent")}`);
+		if (options.interactive === "always" && !isInteractiveTerminal) {
+			console.log("");
+			console.log(dim("Interactive picker requires a TTY. Falling back to command list."));
+		}
+		console.log("");
+	}
+	if (successRows.length > 0) {
+		const maxEntryWidth = Math.max(16, outputWidth - 42 - 14);
+		const widths = {
+			rank: 4,
+			sev: 7,
+			output: 7,
+			deps: 7,
+			local: 7,
+			inputCount: 6,
+			handlerCount: 4,
+			entry: Math.max(16, Math.min(maxEntryWidth, Math.max(...successRows.map((row) => row.entry.length), 5)))
+		};
+		const header = [
+			pad("Rank", widths.rank, "right"),
+			pad("Level", widths.sev),
+			pad("OutMB", widths.output, "right"),
+			pad("DepMB", widths.deps, "right"),
+			pad("LocMB", widths.local, "right"),
+			pad("Files", widths.inputCount, "right"),
+			pad("Fns", widths.handlerCount, "right"),
+			pad("Entry", widths.entry)
+		].join("  ");
+		const divider = [
+			"-".repeat(widths.rank),
+			"-".repeat(widths.sev),
+			"-".repeat(widths.output),
+			"-".repeat(widths.deps),
+			"-".repeat(widths.local),
+			"-".repeat(widths.inputCount),
+			"-".repeat(widths.handlerCount),
+			"-".repeat(widths.entry)
+		].join("  ");
+		console.log(dim(header));
+		console.log(dim(divider));
+		for (const [index, row] of successRows.entries()) {
+			const severity = severityForBytes(row.outputBytes, options);
+			const outputMbValue = Number.parseFloat(toMB(row.outputBytes));
+			console.log([
+				pad(String(index + 1), widths.rank, "right"),
+				colorizePadded(severity, widths.sev, "left", severityColor(severity)),
+				colorizePadded(toMB(row.outputBytes), widths.output, "right", shareColor(outputMbValue / options.dangerMb * 100)),
+				pad(toMB(row.dependencyInputBytes), widths.deps, "right"),
+				pad(toMB(row.localInputBytes), widths.local, "right"),
+				pad(String(row.inputCount), widths.inputCount, "right"),
+				pad(String(row.handlerExports.length), widths.handlerCount, "right"),
+				pad(truncate(row.entry, widths.entry), widths.entry)
+			].join("  "));
+		}
+	}
+	if (failedRows.length > 0) {
+		console.log(`\n${colorize("Failed entries:", ANSI.red)}`);
+		for (const row of failedRows) {
+			const errorLine = firstLine(row.error);
+			const available = Math.max(24, outputWidth - row.entry.length - 4);
+			console.log(`- ${row.entry}: ${truncate(errorLine, available)}`);
+		}
+	}
+	if (includeDeepData) {
+		const detailRows = options.entryPattern ? successRows : successRows.slice(0, options.detailEntries);
+		if (!options.entryPattern && successRows.length > detailRows.length) {
+			console.log("");
+			console.log(dim(`Expanded details for top ${detailRows.length} entries. Pass an entry regex as first arg for a specific module.`));
+		}
+		for (const row of detailRows) {
+			if (row.handlerExports.length > 0) {
+				console.log("");
+				printWrapped({
+					prefix: `${bold("Handlers:")} `,
+					text: row.handlerExports.join(", ")
+				});
+			}
+			printHotspotPackages(row, options);
+			if (options.showInputs) printHotspotTopInputs(row, options);
+		}
+	}
+	let exitCode = 0;
+	if (failedRows.length > 0) exitCode = 1;
+	if (options.failMb !== null && largest && largest.outputBytes / MB >= options.failMb) {
+		console.log("");
+		console.log(colorize(`Fail threshold reached: largest output is ${toMB(largest.outputBytes)} MB (>= ${options.failMb.toFixed(2)} MB).`, ANSI.red));
+		exitCode = 1;
+	}
+	return exitCode;
+};
+const buildDeployBundle = async (entryPoints, externalizeSchema) => build({
+	bundle: true,
+	entryPoints,
+	format: "esm",
+	platform: "browser",
+	target: ["esnext"],
+	write: false,
+	metafile: true,
+	logLevel: "silent",
+	outdir: "out",
+	splitting: true,
+	jsx: "automatic",
+	conditions: ["convex", "module"],
+	minifySyntax: true,
+	minifyIdentifiers: true,
+	minifyWhitespace: false,
+	define: { "process.env.NODE_ENV": "\"production\"" },
+	plugins: externalizeSchema ? [schemaExternalFallbackPlugin] : []
+});
+const printDeployTopInputs = (outputBytes, aggregateInputBytes, options) => {
+	const topInputs = aggregateInputBytes.filter((input) => !isSmallInput(input.bytes, outputBytes, options.showSmall)).slice(0, options.topInputs);
+	if (topInputs.length === 0) return;
+	console.log("");
+	console.log(bold("Top inputs (deploy bundle):"));
+	const inputPathWidth = Math.max(18, outputWidth - 46);
+	console.log(dim(`bytesInOutput    share       impact  ${pad("path", inputPathWidth)}`));
+	console.log(dim(`-------------  ----------  ----------------  ${"-".repeat(inputPathWidth)}`));
+	for (const input of topInputs) {
+		const share = outputBytes > 0 ? input.bytes / outputBytes * 100 : 0;
+		const sharePct = colorize(`${share.toFixed(2)}%`.padStart(10), shareColor(share));
+		const bar = makeShareBar(share);
+		console.log(`${input.bytes.toString().padStart(13)}  ${sharePct}  ${bar}  ${compactPath(input.inputPath, inputPathWidth)}`);
+	}
+};
+const printDeployTopPackages = (outputBytes, aggregateInputBytes, options) => {
+	const packageMap = /* @__PURE__ */ new Map();
+	for (const item of aggregateInputBytes) {
+		const packageName = packageFromInputPath(item.inputPath);
+		const current = packageMap.get(packageName) ?? { bytes: 0 };
+		current.bytes += item.bytes;
+		packageMap.set(packageName, current);
+	}
+	const topRows = Array.from(packageMap.entries()).map(([packageName, value]) => ({
+		packageName,
+		bytes: value.bytes
+	})).sort((a, b) => b.bytes - a.bytes).filter((item) => !isSmallInput(item.bytes, outputBytes, options.showSmall)).slice(0, options.topPackages);
+	if (topRows.length === 0) return;
+	console.log("");
+	console.log(bold("Top packages (deploy bundle):"));
+	const packageColWidth = Math.max(16, Math.min(30, outputWidth - 58));
+	const barWidth = Math.max(8, Math.min(16, outputWidth - (packageColWidth + 52)));
+	for (const [index, item] of topRows.entries()) {
+		const share = outputBytes > 0 ? item.bytes / outputBytes * 100 : 0;
+		const shareStr = colorize(`${share.toFixed(2)}%`, shareColor(share));
+		const sizeStr = colorize(`${toMB(item.bytes)} MB`, shareColor(share));
+		const bar = makeShareBar(share, barWidth);
+		const packageLabel = truncate(item.packageName, packageColWidth);
+		console.log(`${bold(`${index + 1}.`)} ${pad(packageLabel, packageColWidth)} ${pad(sizeStr, 18)} ${pad(shareStr, 10)} ${bar}`);
+	}
+};
+const runDeployAnalysis = async (roots, options) => {
+	const { entryPoints, nodeEntryPoints } = await collectAnalyzeEntrySelection(roots, options);
+	if (entryPoints.length === 0) {
+		console.log("No Convex handler entries found to analyze (files exporting query/mutation/action, including internal variants).");
+		return 0;
+	}
+	let result;
+	let schemaExternalized = false;
+	try {
+		result = await buildDeployBundle(entryPoints, false);
+	} catch (error) {
+		if (!shouldRetryWithSchemaExternalized(error)) throw error;
+		result = await buildDeployBundle(entryPoints, true);
+		schemaExternalized = true;
+	}
+	const meta = result.metafile;
+	if (!meta) throw new Error("No metafile generated for deploy analysis.");
+	const jsOutputs = Object.entries(meta.outputs).filter(([outputPath]) => !outputPath.endsWith(".map")).map(([outputPath, value]) => ({
+		outputPath,
+		...value
+	})).filter((output) => output.outputPath.endsWith(".js"));
+	const totalOutputBytes = jsOutputs.reduce((sum, output) => sum + output.bytes, 0);
+	const entryOutputs = jsOutputs.filter((output) => !!output.entryPoint).map((output) => ({
+		outputPath: output.outputPath,
+		entryPoint: output.entryPoint,
+		bytes: output.bytes,
+		inputCount: Object.keys(output.inputs ?? {}).length
+	})).sort((a, b) => b.bytes - a.bytes);
+	const sharedChunks = jsOutputs.filter((output) => !output.entryPoint).map((output) => ({
+		outputPath: output.outputPath,
+		bytes: output.bytes
+	})).sort((a, b) => b.bytes - a.bytes);
+	const aggregateInputs = /* @__PURE__ */ new Map();
+	for (const output of jsOutputs) for (const [inputPath, value] of Object.entries(output.inputs ?? {})) {
+		const bytesInOutput = value.bytesInOutput ?? 0;
+		aggregateInputs.set(inputPath, (aggregateInputs.get(inputPath) ?? 0) + bytesInOutput);
+	}
+	const aggregateInputRows = Array.from(aggregateInputs.entries()).map(([inputPath, bytes]) => ({
+		inputPath,
+		bytes
+	})).sort((a, b) => b.bytes - a.bytes);
+	const largestEntry = entryOutputs.at(0);
+	const largestChunk = sharedChunks.at(0);
+	console.log(bold("Runtime deploy analysis (isolate bundle)"));
+	console.log(`entries=${entryPoints.length} nodeEntriesSkipped=${nodeEntryPoints.length} outputs=${jsOutputs.length} total=${formatBytes(totalOutputBytes)}`);
+	if (schemaExternalized) console.log(colorize("note: schema imports were externalized after a build error; dependency sizes are approximate.", ANSI.yellow));
+	if (largestEntry) console.log(`largestEntry=${shortPath(largestEntry.entryPoint)} (${formatBytes(largestEntry.bytes)})`);
+	if (largestChunk) console.log(`largestSharedChunk=${shortPath(largestChunk.outputPath)} (${formatBytes(largestChunk.bytes)})`);
+	console.log("");
+	const topEntries = entryOutputs.slice(0, 15);
+	if (topEntries.length > 0) {
+		const widths = {
+			rank: 4,
+			sev: 7,
+			output: 7,
+			inputs: 6,
+			entry: Math.max(24, Math.min(72, outputWidth - 34))
+		};
+		console.log(dim(`${pad("Rank", widths.rank, "right")}  ${pad("Level", widths.sev)}  ${pad("OutMB", widths.output, "right")}  ${pad("In", widths.inputs, "right")}  ${pad("Entry", widths.entry)}`));
+		console.log(dim(`${"-".repeat(widths.rank)}  ${"-".repeat(widths.sev)}  ${"-".repeat(widths.output)}  ${"-".repeat(widths.inputs)}  ${"-".repeat(widths.entry)}`));
+		for (const [index, row] of topEntries.entries()) {
+			const severity = severityForBytes(row.bytes, options);
+			console.log(`${pad(String(index + 1), widths.rank, "right")}  ${colorizePadded(severity, widths.sev, "left", severityColor(severity))}  ${colorizePadded(toMB(row.bytes), widths.output, "right", shareColor(row.bytes / MB / options.dangerMb * 100))}  ${pad(String(row.inputCount), widths.inputs, "right")}  ${pad(truncate(shortPath(row.entryPoint), widths.entry), widths.entry)}`);
+		}
+	}
+	const topChunks = sharedChunks.slice(0, 8);
+	if (topChunks.length > 0) {
+		console.log("");
+		console.log(bold("Top shared chunks:"));
+		for (const chunk of topChunks) {
+			const share = totalOutputBytes > 0 ? chunk.bytes / totalOutputBytes * 100 : 0;
+			const severity = severityForBytes(chunk.bytes, options);
+			console.log(`${colorize(`[${severity}]`, severityColor(severity))} ${pad(`${toMB(chunk.bytes)} MB`, 10, "right")} ${pad(`${share.toFixed(2)}%`, 8, "right")} ${shortPath(chunk.outputPath)}`);
+		}
+	}
+	if (options.details) {
+		printDeployTopPackages(totalOutputBytes, aggregateInputRows, options);
+		printDeployTopInputs(totalOutputBytes, aggregateInputRows, options);
+	}
+	const largestBytes = Math.max(largestEntry?.bytes ?? 0, largestChunk?.bytes ?? 0);
+	if (options.failMb !== null && largestBytes / MB >= options.failMb) {
+		console.log("");
+		printWrapped({
+			text: `Fail threshold reached: largest output is ${toMB(largestBytes)} MB (>= ${options.failMb.toFixed(2)} MB).`,
+			color: ANSI.red
+		});
+		return 1;
+	}
+	return 0;
+};
+async function runAnalyze(argv) {
+	const options = parseArgs$1(argv);
+	colorEnabled = supportsColor;
+	outputWidth = options.width ?? process.stdout.columns ?? DEFAULT_OUTPUT_WIDTH;
+	const roots = detectProjectRoots();
+	if (options.mode === "hotspot") return runHotspotAnalysis(roots, options);
+	return runDeployAnalysis(roots, options);
+}
+
+//#endregion
+//#region src/cli/config.ts
+const DEFAULT_CONFIG_PATH = "better-convex.json";
+const CODEGEN_SCOPES = new Set([
+	"all",
+	"auth",
+	"orm"
+]);
+const BACKFILL_ENABLED_VALUES = new Set([
+	"auto",
+	"on",
+	"off"
+]);
+function createDefaultConfig() {
+	return {
+		api: true,
+		auth: true,
+		outputDir: "convex/shared",
+		dev: {
+			debug: false,
+			convexArgs: [],
+			aggregateBackfill: {
+				enabled: "auto",
+				wait: true,
+				batchSize: 1e3,
+				pollIntervalMs: 1e3,
+				timeoutMs: 9e5,
+				strict: false
+			}
+		},
+		codegen: {
+			debug: false,
+			convexArgs: []
+		},
+		deploy: {
+			convexArgs: [],
+			aggregateBackfill: {
+				enabled: "auto",
+				wait: true,
+				batchSize: 1e3,
+				pollIntervalMs: 1e3,
+				timeoutMs: 9e5,
+				strict: true
+			}
+		}
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseBoolean(value, fieldName, configPath) {
+	if (typeof value === "boolean") return value;
+	throw new Error(`Invalid ${fieldName} in ${configPath}: expected boolean, got ${typeof value}.`);
+}
+function parseString(value, fieldName, configPath) {
+	if (typeof value === "string" && value.length > 0) return value;
+	throw new Error(`Invalid ${fieldName} in ${configPath}: expected non-empty string.`);
+}
+function parseStringArray(value, fieldName, configPath) {
+	if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) throw new Error(`Invalid ${fieldName} in ${configPath}: expected string array.`);
+	return [...value];
+}
+function parsePositiveInteger(value, fieldName, configPath) {
+	if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+	throw new Error(`Invalid ${fieldName} in ${configPath}: expected a positive integer.`);
+}
+function parseScope(value, fieldName, configPath) {
+	if (typeof value === "string" && CODEGEN_SCOPES.has(value)) return value;
+	throw new Error(`Invalid ${fieldName} in ${configPath}: expected one of all, auth, orm.`);
+}
+function parseBackfillEnabled(value, fieldName, configPath) {
+	if (value === true) return "on";
+	if (value === false) return "off";
+	if (typeof value === "string" && BACKFILL_ENABLED_VALUES.has(value)) return value;
+	throw new Error(`Invalid ${fieldName} in ${configPath}: expected boolean or one of auto, on, off.`);
+}
+function parseAggregateBackfillConfig(value, fieldName, configPath) {
+	if (!isRecord(value)) throw new Error(`Invalid ${fieldName} in ${configPath}: expected object.`);
+	const parsed = {};
+	if ("enabled" in value) parsed.enabled = parseBackfillEnabled(value.enabled, `${fieldName}.enabled`, configPath);
+	if ("wait" in value) parsed.wait = parseBoolean(value.wait, `${fieldName}.wait`, configPath);
+	if ("batchSize" in value) parsed.batchSize = parsePositiveInteger(value.batchSize, `${fieldName}.batchSize`, configPath);
+	if ("pollIntervalMs" in value) parsed.pollIntervalMs = parsePositiveInteger(value.pollIntervalMs, `${fieldName}.pollIntervalMs`, configPath);
+	if ("timeoutMs" in value) parsed.timeoutMs = parsePositiveInteger(value.timeoutMs, `${fieldName}.timeoutMs`, configPath);
+	if ("strict" in value) parsed.strict = parseBoolean(value.strict, `${fieldName}.strict`, configPath);
+	return parsed;
+}
+function parseCommandConfig(value, fieldName, configPath) {
+	if (!isRecord(value)) throw new Error(`Invalid ${fieldName} in ${configPath}: expected object.`);
+	const parsed = {};
+	if ("debug" in value) parsed.debug = parseBoolean(value.debug, `${fieldName}.debug`, configPath);
+	if ("convexArgs" in value) parsed.convexArgs = parseStringArray(value.convexArgs, `${fieldName}.convexArgs`, configPath);
+	if (fieldName === "codegen" && "scope" in value && value.scope !== void 0) parsed.scope = parseScope(value.scope, `${fieldName}.scope`, configPath);
+	if (fieldName === "dev" && "aggregateBackfill" in value && value.aggregateBackfill !== void 0) parsed.aggregateBackfill = parseAggregateBackfillConfig(value.aggregateBackfill, `${fieldName}.aggregateBackfill`, configPath);
+	return parsed;
+}
+function parseDeployConfig(value, configPath) {
+	if (!isRecord(value)) throw new Error(`Invalid deploy in ${configPath}: expected object.`);
+	const parsed = {};
+	if ("convexArgs" in value) parsed.convexArgs = parseStringArray(value.convexArgs, "deploy.convexArgs", configPath);
+	if ("aggregateBackfill" in value && value.aggregateBackfill !== void 0) parsed.aggregateBackfill = parseAggregateBackfillConfig(value.aggregateBackfill, "deploy.aggregateBackfill", configPath);
+	return parsed;
+}
+function loadBetterConvexConfig(configPathArg) {
+	const resolvedConfigPath = path.resolve(process.cwd(), configPathArg ?? DEFAULT_CONFIG_PATH);
+	const hasExplicitConfigPath = typeof configPathArg === "string";
+	if (!fs.existsSync(resolvedConfigPath)) {
+		if (hasExplicitConfigPath) throw new Error(`Config file not found: ${resolvedConfigPath}`);
+		return createDefaultConfig();
+	}
+	let rawConfig;
+	try {
+		rawConfig = JSON.parse(fs.readFileSync(resolvedConfigPath, "utf-8"));
+	} catch (error) {
+		throw new Error(`Failed to parse config file ${resolvedConfigPath}: ${error.message}`);
+	}
+	if (!isRecord(rawConfig)) throw new Error(`Invalid config file ${resolvedConfigPath}: expected top-level object.`);
+	const config = createDefaultConfig();
+	if ("api" in rawConfig) config.api = parseBoolean(rawConfig.api, "api", resolvedConfigPath);
+	if ("auth" in rawConfig) config.auth = parseBoolean(rawConfig.auth, "auth", resolvedConfigPath);
+	if ("outputDir" in rawConfig) config.outputDir = parseString(rawConfig.outputDir, "outputDir", resolvedConfigPath);
+	if ("dev" in rawConfig) {
+		const parsed = parseCommandConfig(rawConfig.dev, "dev", resolvedConfigPath);
+		if (parsed.debug !== void 0) config.dev.debug = parsed.debug;
+		if (parsed.convexArgs !== void 0) config.dev.convexArgs = parsed.convexArgs;
+		if (parsed.aggregateBackfill !== void 0) config.dev.aggregateBackfill = {
+			...config.dev.aggregateBackfill,
+			...parsed.aggregateBackfill
+		};
+	}
+	if ("codegen" in rawConfig) {
+		const parsed = parseCommandConfig(rawConfig.codegen, "codegen", resolvedConfigPath);
+		if (parsed.debug !== void 0) config.codegen.debug = parsed.debug;
+		if (parsed.convexArgs !== void 0) config.codegen.convexArgs = parsed.convexArgs;
+		if (parsed.scope !== void 0) config.codegen.scope = parsed.scope;
+	}
+	if ("deploy" in rawConfig) {
+		const parsed = parseDeployConfig(rawConfig.deploy, resolvedConfigPath);
+		if (parsed.convexArgs !== void 0) config.deploy.convexArgs = parsed.convexArgs;
+		if (parsed.aggregateBackfill !== void 0) config.deploy.aggregateBackfill = {
+			...config.deploy.aggregateBackfill,
+			...parsed.aggregateBackfill
+		};
+	}
+	return config;
+}
+
+//#endregion
 //#region src/cli/env.ts
 async function syncEnv(options = {}) {
 	const { auth = false, force = false, prod = false } = options;
@@ -111,9 +2007,20 @@ async function syncEnv(options = {}) {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const realConvex = join(dirname(createRequire(import.meta.url).resolve("convex/package.json")), "bin/main.js");
+const MISSING_BACKFILL_FUNCTION_RE = /could not find function|function .* was not found|unknown function/i;
+const GITIGNORE_CONVEX_ENTRY_RE = /(^|\r?\n)\.convex\/?\s*(\r?\n|$)/m;
+const AGGREGATE_STATE_RELATIVE_PATH = join(".convex", "better-convex", "aggregate-backfill-state.json");
+const AGGREGATE_STATE_VERSION = 1;
+const VALID_SCOPES = new Set([
+	"all",
+	"auth",
+	"orm"
+]);
 function parseArgs(argv) {
 	let debug = false;
 	let outputDir;
+	let scope;
+	let configPath;
 	const filtered = [];
 	for (let i = 0; i < argv.length; i++) {
 		const a = argv[i];
@@ -121,8 +2028,24 @@ function parseArgs(argv) {
 			debug = true;
 			continue;
 		}
-		if (a === "--meta") {
-			outputDir = argv[i + 1];
+		if (a === "--api") {
+			const value = argv[i + 1];
+			if (!value) throw new Error("Missing value for --api.");
+			outputDir = value;
+			i += 1;
+			continue;
+		}
+		if (a === "--scope") {
+			const value = argv[i + 1];
+			if (!value || !VALID_SCOPES.has(value)) throw new Error(`Invalid --scope value "${value ?? ""}". Expected one of: all, auth, orm.`);
+			scope = value;
+			i += 1;
+			continue;
+		}
+		if (a === "--config") {
+			const value = argv[i + 1];
+			if (!value) throw new Error("Missing value for --config.");
+			configPath = value;
 			i += 1;
 			continue;
 		}
@@ -135,24 +2058,519 @@ function parseArgs(argv) {
 		restArgs,
 		convexArgs: restArgs,
 		debug,
-		outputDir
+		outputDir,
+		scope,
+		configPath
 	};
 }
+const DEFAULT_AGGREGATE_FINGERPRINT_STATE = {
+	version: AGGREGATE_STATE_VERSION,
+	entries: {}
+};
+function normalizeStringList(values) {
+	if (!Array.isArray(values)) return [];
+	return [...new Set(values.filter((value) => typeof value === "string"))].sort();
+}
+function readOptionalCliFlagValue(args, flag) {
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === flag) {
+			const value = args[i + 1];
+			if (value) return value;
+			continue;
+		}
+		const withEquals = `${flag}=`;
+		if (arg.startsWith(withEquals)) {
+			const value = arg.slice(withEquals.length);
+			if (value) return value;
+		}
+	}
+}
+function collectSchemaTables(schemaModule) {
+	const allTables = /* @__PURE__ */ new Set();
+	const relations = schemaModule.relations;
+	if (relations && typeof relations === "object" && !Array.isArray(relations)) for (const relationConfig of Object.values(relations)) {
+		const table = relationConfig?.table;
+		if (table) allTables.add(table);
+	}
+	const tables = schemaModule.tables;
+	if (tables && typeof tables === "object" && !Array.isArray(tables)) {
+		for (const table of Object.values(tables)) if (table) allTables.add(table);
+	}
+	return [...allTables];
+}
+function buildAggregateFingerprintPayload(tables) {
+	return tables.map((table) => getTableConfig(table)).map((tableConfig) => ({
+		tableName: tableConfig.name,
+		aggregateIndexes: tableConfig.aggregateIndexes.map((index) => ({
+			name: index.name,
+			fields: normalizeStringList(index.fields),
+			countFields: normalizeStringList(index.countFields),
+			sumFields: normalizeStringList(index.sumFields),
+			avgFields: normalizeStringList(index.avgFields),
+			minFields: normalizeStringList(index.minFields),
+			maxFields: normalizeStringList(index.maxFields)
+		})).sort((a, b) => a.name.localeCompare(b.name))
+	})).sort((a, b) => a.tableName.localeCompare(b.tableName));
+}
+async function computeAggregateIndexFingerprint(functionsDir) {
+	const schemaPath = join(functionsDir, "schema.ts");
+	if (!fs.existsSync(schemaPath)) return null;
+	const schemaModule = await createJiti(process.cwd(), {
+		interopDefault: true,
+		moduleCache: false
+	}).import(schemaPath);
+	if (!schemaModule || typeof schemaModule !== "object") return null;
+	const tables = collectSchemaTables(schemaModule);
+	if (tables.length === 0) return null;
+	const payload = buildAggregateFingerprintPayload(tables);
+	return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+function getDevAggregateBackfillStatePath(cwd = process.cwd()) {
+	return join(cwd, AGGREGATE_STATE_RELATIVE_PATH);
+}
+function readAggregateFingerprintState(statePath) {
+	if (!fs.existsSync(statePath)) return {
+		...DEFAULT_AGGREGATE_FINGERPRINT_STATE,
+		entries: {}
+	};
+	try {
+		const raw = fs.readFileSync(statePath, "utf8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null || typeof parsed.entries !== "object" || parsed.entries === null) return {
+			...DEFAULT_AGGREGATE_FINGERPRINT_STATE,
+			entries: {}
+		};
+		return {
+			version: AGGREGATE_STATE_VERSION,
+			entries: Object.fromEntries(Object.entries(parsed.entries).filter(([, value]) => typeof value === "object" && value !== null && typeof value.fingerprint === "string"))
+		};
+	} catch {
+		return {
+			...DEFAULT_AGGREGATE_FINGERPRINT_STATE,
+			entries: {}
+		};
+	}
+}
+function writeAggregateFingerprintState(statePath, state) {
+	fs.mkdirSync(dirname(statePath), { recursive: true });
+	const tmpPath = `${statePath}.tmp`;
+	fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2));
+	fs.renameSync(tmpPath, statePath);
+}
+function getAggregateBackfillDeploymentKey(args) {
+	if (args.includes("--prod")) return "prod";
+	const deploymentName = readOptionalCliFlagValue(args, "--deployment-name");
+	if (deploymentName) return `deployment:${deploymentName}`;
+	const previewName = readOptionalCliFlagValue(args, "--preview-name");
+	if (previewName) return `preview:${previewName}`;
+	return "local";
+}
+function ensureConvexGitignoreEntry(cwd = process.cwd()) {
+	let currentDir = resolve(cwd);
+	let gitRoot = null;
+	while (true) {
+		if (fs.existsSync(join(currentDir, ".git"))) {
+			gitRoot = currentDir;
+			break;
+		}
+		const parent = dirname(currentDir);
+		if (parent === currentDir) break;
+		currentDir = parent;
+	}
+	if (!gitRoot) return;
+	const gitignorePath = join(gitRoot, ".gitignore");
+	const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf8") : "";
+	if (GITIGNORE_CONVEX_ENTRY_RE.test(existing)) return;
+	const normalized = existing.endsWith("\n") || existing.length === 0 ? existing : `${existing}\n`;
+	fs.writeFileSync(gitignorePath, `${normalized}.convex/\n`);
+}
 const processes = [];
 function cleanup() {
 	for (const proc of processes) if (proc && !proc.killed) proc.kill("SIGTERM");
 }
+function deriveScopeFromToggles(api, auth) {
+	if (api && auth) return "all";
+	if (!api && auth) return "auth";
+	if (!api && !auth) return "orm";
+	return null;
+}
+const VALID_BACKFILL_ENABLED = new Set([
+	"auto",
+	"on",
+	"off"
+]);
+function parsePositiveIntegerArg(flag, raw) {
+	const parsed = Number(raw);
+	if (!Number.isInteger(parsed) || parsed < 1) throw new Error(`${flag} expects a positive integer.`);
+	return parsed;
+}
+function readFlagValue(args, index, flag) {
+	const value = args[index + 1];
+	if (!value) throw new Error(`Missing value for ${flag}.`);
+	return {
+		value,
+		nextIndex: index + 1
+	};
+}
+function extractBackfillCliOptions(args) {
+	const remainingArgs = [];
+	const overrides = {};
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--force") continue;
+		if (arg === "--backfill") {
+			const { value, nextIndex } = readFlagValue(args, i, "--backfill");
+			if (!VALID_BACKFILL_ENABLED.has(value)) throw new Error("Invalid --backfill value. Expected auto, on, or off.");
+			overrides.enabled = value;
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--backfill=")) {
+			const value = arg.slice(11);
+			if (!VALID_BACKFILL_ENABLED.has(value)) throw new Error("Invalid --backfill value. Expected auto, on, or off.");
+			overrides.enabled = value;
+			continue;
+		}
+		if (arg === "--backfill-mode") {
+			readFlagValue(args, i, "--backfill-mode");
+			throw new Error("`--backfill-mode` was removed. Use `better-convex aggregate rebuild`.");
+		}
+		if (arg.startsWith("--backfill-mode=")) throw new Error("`--backfill-mode` was removed. Use `better-convex aggregate rebuild`.");
+		if (arg === "--backfill-wait") {
+			overrides.wait = true;
+			continue;
+		}
+		if (arg === "--no-backfill-wait") {
+			overrides.wait = false;
+			continue;
+		}
+		if (arg === "--backfill-strict") {
+			overrides.strict = true;
+			continue;
+		}
+		if (arg === "--no-backfill-strict") {
+			overrides.strict = false;
+			continue;
+		}
+		if (arg === "--backfill-batch-size") {
+			const { value, nextIndex } = readFlagValue(args, i, "--backfill-batch-size");
+			overrides.batchSize = parsePositiveIntegerArg("--backfill-batch-size", value);
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--backfill-batch-size=")) {
+			overrides.batchSize = parsePositiveIntegerArg("--backfill-batch-size", arg.slice(22));
+			continue;
+		}
+		if (arg === "--backfill-timeout-ms") {
+			const { value, nextIndex } = readFlagValue(args, i, "--backfill-timeout-ms");
+			overrides.timeoutMs = parsePositiveIntegerArg("--backfill-timeout-ms", value);
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--backfill-timeout-ms=")) {
+			overrides.timeoutMs = parsePositiveIntegerArg("--backfill-timeout-ms", arg.slice(22));
+			continue;
+		}
+		if (arg === "--backfill-poll-ms") {
+			const { value, nextIndex } = readFlagValue(args, i, "--backfill-poll-ms");
+			overrides.pollIntervalMs = parsePositiveIntegerArg("--backfill-poll-ms", value);
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--backfill-poll-ms=")) {
+			overrides.pollIntervalMs = parsePositiveIntegerArg("--backfill-poll-ms", arg.slice(19));
+			continue;
+		}
+		remainingArgs.push(arg);
+	}
+	return {
+		remainingArgs,
+		overrides
+	};
+}
+function extractResetCliOptions(args) {
+	const remainingArgs = [];
+	let confirmed = false;
+	let beforeHook;
+	let afterHook;
+	const isBackfillFlag = (arg) => arg === "--backfill" || arg.startsWith("--backfill=") || arg.startsWith("--backfill-") || arg.startsWith("--no-backfill-");
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (isBackfillFlag(arg)) throw new Error("`better-convex reset` does not accept backfill flags. It always runs aggregateBackfill in resume mode.");
+		if (arg === "--yes") {
+			confirmed = true;
+			continue;
+		}
+		if (arg === "--before") {
+			const { value, nextIndex } = readFlagValue(args, i, "--before");
+			beforeHook = value;
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--before=")) {
+			const value = arg.slice(9);
+			if (!value) throw new Error("Missing value for --before.");
+			beforeHook = value;
+			continue;
+		}
+		if (arg === "--after") {
+			const { value, nextIndex } = readFlagValue(args, i, "--after");
+			afterHook = value;
+			i = nextIndex;
+			continue;
+		}
+		if (arg.startsWith("--after=")) {
+			const value = arg.slice(8);
+			if (!value) throw new Error("Missing value for --after.");
+			afterHook = value;
+			continue;
+		}
+		remainingArgs.push(arg);
+	}
+	return {
+		confirmed,
+		beforeHook,
+		afterHook,
+		remainingArgs
+	};
+}
+function resolveBackfillConfig(base, overrides) {
+	const resolvedBase = base ?? {
+		enabled: "auto",
+		wait: true,
+		batchSize: 1e3,
+		timeoutMs: 9e5,
+		pollIntervalMs: 1e3,
+		strict: false
+	};
+	return {
+		...resolvedBase,
+		enabled: overrides.enabled ?? resolvedBase.enabled,
+		wait: overrides.wait ?? resolvedBase.wait,
+		batchSize: overrides.batchSize ?? resolvedBase.batchSize,
+		timeoutMs: overrides.timeoutMs ?? resolvedBase.timeoutMs,
+		pollIntervalMs: overrides.pollIntervalMs ?? resolvedBase.pollIntervalMs,
+		strict: overrides.strict ?? resolvedBase.strict
+	};
+}
+function extractRunDeploymentArgs(args) {
+	const deploymentArgs = [];
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--prod") {
+			deploymentArgs.push(arg);
+			continue;
+		}
+		if (arg === "--preview-name" || arg === "--deployment-name" || arg === "--env-file" || arg === "--component") {
+			const value = args[i + 1];
+			if (!value) throw new Error(`Missing value for ${arg}.`);
+			deploymentArgs.push(arg, value);
+			i += 1;
+			continue;
+		}
+		if (arg.startsWith("--preview-name=") || arg.startsWith("--deployment-name=") || arg.startsWith("--env-file=") || arg.startsWith("--component=")) deploymentArgs.push(arg);
+	}
+	return deploymentArgs;
+}
+function isMissingBackfillFunctionOutput(output) {
+	return MISSING_BACKFILL_FUNCTION_RE.test(output);
+}
+function parseConvexRunJson(stdout) {
+	const trimmed = stdout.trim();
+	if (trimmed.length === 0) return [];
+	try {
+		return JSON.parse(trimmed);
+	} catch {
+		const lines = trimmed.split("\n").map((line) => line.trim()).filter(Boolean);
+		for (let i = lines.length - 1; i >= 0; i -= 1) {
+			const line = lines[i];
+			try {
+				return JSON.parse(line);
+			} catch {}
+		}
+	}
+	throw new Error(`Failed to parse convex run output as JSON.\nOutput:\n${stdout.trim()}`);
+}
+function sleep(ms, signal) {
+	if (signal?.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		};
+		signal?.addEventListener("abort", onAbort);
+	});
+}
+async function runConvexFunction(execaFn, realConvexPath, functionName, args, deploymentArgs, options) {
+	const result = await execaFn("node", [
+		realConvexPath,
+		"run",
+		...deploymentArgs,
+		functionName,
+		JSON.stringify(args)
+	], {
+		cwd: process.cwd(),
+		reject: false,
+		stdio: "pipe"
+	});
+	const stdout = typeof result.stdout === "string" ? result.stdout : "";
+	const stderr = typeof result.stderr === "string" ? result.stderr : "";
+	if (options?.echoOutput !== false) {
+		if (stdout) process.stdout.write(stdout.endsWith("\n") ? stdout : `${stdout}\n`);
+		if (stderr) process.stderr.write(stderr.endsWith("\n") ? stderr : `${stderr}\n`);
+	}
+	return {
+		exitCode: result.exitCode ?? 1,
+		stdout,
+		stderr
+	};
+}
+async function runAggregateBackfillFlow(params) {
+	const { execaFn, realConvexPath, backfillConfig, mode, deploymentArgs, signal, context } = params;
+	if (signal?.aborted) return 0;
+	if (backfillConfig.enabled === "off") return 0;
+	const kickoff = await runConvexFunction(execaFn, realConvexPath, "generated/server:aggregateBackfill", {
+		mode,
+		batchSize: backfillConfig.batchSize
+	}, deploymentArgs, { echoOutput: false });
+	if (kickoff.exitCode !== 0) {
+		const combinedOutput = `${kickoff.stdout}\n${kickoff.stderr}`;
+		if (backfillConfig.enabled === "auto" && isMissingBackfillFunctionOutput(combinedOutput)) {
+			if (context === "deploy") console.info("ℹ️  aggregateBackfill not found in this deployment; skipping post-deploy backfill (auto mode).");
+			return 0;
+		}
+		return kickoff.exitCode;
+	}
+	const kickoffPayload = parseConvexRunJson(kickoff.stdout);
+	const needsRebuild = typeof kickoffPayload === "object" && kickoffPayload !== null && !Array.isArray(kickoffPayload) && typeof kickoffPayload.needsRebuild === "number" ? kickoffPayload.needsRebuild : 0;
+	const scheduled = typeof kickoffPayload === "object" && kickoffPayload !== null && !Array.isArray(kickoffPayload) && typeof kickoffPayload.scheduled === "number" ? kickoffPayload.scheduled : 0;
+	const targets = typeof kickoffPayload === "object" && kickoffPayload !== null && !Array.isArray(kickoffPayload) && typeof kickoffPayload.targets === "number" ? kickoffPayload.targets : 0;
+	const pruned = typeof kickoffPayload === "object" && kickoffPayload !== null && !Array.isArray(kickoffPayload) && typeof kickoffPayload.pruned === "number" ? kickoffPayload.pruned : 0;
+	if (pruned > 0) console.info(`ℹ️  aggregateBackfill pruned ${pruned} removed indexes`);
+	if (mode === "resume" && needsRebuild > 0) {
+		const message = `Aggregate backfill found ${needsRebuild} index definitions that require rebuild. Run \`better-convex aggregate rebuild\` for this deployment.`;
+		if (backfillConfig.strict) {
+			console.error(`❌ ${message}`);
+			return 1;
+		}
+		console.warn(`⚠️  ${message}`);
+	} else if (scheduled > 0) console.info(`ℹ️  aggregateBackfill scheduled ${scheduled}/${targets} target indexes`);
+	if (!backfillConfig.wait || signal?.aborted) return 0;
+	const deadline = Date.now() + backfillConfig.timeoutMs;
+	let lastProgress = "";
+	while (!signal?.aborted) {
+		const statusResult = await runConvexFunction(execaFn, realConvexPath, "generated/server:aggregateBackfillStatus", {}, deploymentArgs, { echoOutput: false });
+		if (statusResult.exitCode !== 0) return statusResult.exitCode;
+		const statuses = parseConvexRunJson(statusResult.stdout);
+		const failed = statuses.find((entry) => Boolean(entry.lastError));
+		if (failed) {
+			console.error(`❌ Aggregate backfill failed for ${failed.tableName}.${failed.indexName}: ${failed.lastError}`);
+			return backfillConfig.strict ? 1 : 0;
+		}
+		const total = statuses.length;
+		const ready = statuses.filter((entry) => entry.status === "READY").length;
+		const progress = `${ready}/${total}`;
+		if (progress !== lastProgress) {
+			lastProgress = progress;
+			if (total > 0) console.info(`ℹ️  aggregateBackfill progress ${ready}/${total} READY`);
+		}
+		if (total === 0 || ready === total) return 0;
+		if (Date.now() > deadline) {
+			const timeoutMessage = `Aggregate backfill timed out after ${backfillConfig.timeoutMs}ms (${ready}/${total} READY).`;
+			if (backfillConfig.strict) {
+				console.error(`❌ ${timeoutMessage}`);
+				return 1;
+			}
+			console.warn(`⚠️  ${timeoutMessage}`);
+			return 0;
+		}
+		await sleep(backfillConfig.pollIntervalMs, signal);
+	}
+	return 0;
+}
+async function runAggregatePruneFlow(params) {
+	const { execaFn, realConvexPath, deploymentArgs } = params;
+	const result = await runConvexFunction(execaFn, realConvexPath, "generated/server:aggregateBackfill", { mode: "prune" }, deploymentArgs, { echoOutput: false });
+	if (result.exitCode !== 0) return result.exitCode;
+	const payload = parseConvexRunJson(result.stdout);
+	const pruned = typeof payload === "object" && payload !== null && !Array.isArray(payload) && typeof payload.pruned === "number" ? payload.pruned : 0;
+	if (pruned > 0) console.info(`ℹ️  aggregateBackfill pruned ${pruned} removed indexes`);
+	else console.info("ℹ️  aggregateBackfill prune no-op");
+	return 0;
+}
+async function runDevSchemaBackfillIfNeeded(params) {
+	const { execaFn, realConvexPath, backfillConfig, functionsDir, deploymentArgs, signal } = params;
+	const fingerprint = await computeAggregateIndexFingerprint(functionsDir);
+	if (!fingerprint) return 0;
+	const deploymentKey = getAggregateBackfillDeploymentKey(deploymentArgs);
+	const statePath = getDevAggregateBackfillStatePath();
+	const state = readAggregateFingerprintState(statePath);
+	if (state.entries[deploymentKey]?.fingerprint === fingerprint) return 0;
+	console.info(`ℹ️  aggregateBackfill resume (${deploymentKey} schema change)`);
+	const exitCode = await runAggregateBackfillFlow({
+		execaFn,
+		realConvexPath,
+		backfillConfig: {
+			...backfillConfig,
+			enabled: "on"
+		},
+		mode: "resume",
+		deploymentArgs,
+		signal,
+		context: "dev"
+	});
+	if (exitCode !== 0 || signal.aborted) return exitCode;
+	state.entries[deploymentKey] = {
+		fingerprint,
+		updatedAt: Date.now()
+	};
+	writeAggregateFingerprintState(statePath, state);
+	return 0;
+}
 async function run(argv, deps) {
-	const { execa: execaFn, generateMeta: generateMetaFn, syncEnv: syncEnvFn, realConvex: realConvexPath } = {
+	const { execa: execaFn, runAnalyze: runAnalyzeFn, generateMeta: generateMetaFn, getConvexConfig: getConvexConfigFn, syncEnv: syncEnvFn, loadBetterConvexConfig: loadBetterConvexConfigFn, ensureConvexGitignoreEntry: ensureConvexGitignoreEntryFn, enableDevSchemaWatch, realConvex: realConvexPath } = {
 		execa,
+		runAnalyze,
 		generateMeta,
+		getConvexConfig,
 		syncEnv,
+		loadBetterConvexConfig,
+		ensureConvexGitignoreEntry,
+		enableDevSchemaWatch: !deps,
 		realConvex,
 		...deps
 	};
-	const { command, restArgs, convexArgs, debug, outputDir } = parseArgs(argv);
+	const { command, restArgs, convexArgs, debug: cliDebug, outputDir: cliOutputDir, scope: cliScope, configPath } = parseArgs(argv);
 	if (command === "dev") {
-		await generateMetaFn(outputDir, { debug });
+		if (cliScope) throw new Error("`--scope` is not supported for `better-convex dev`. Use `better-convex codegen --scope <all|auth|orm>` for scoped generation.");
+		const config = loadBetterConvexConfigFn(configPath);
+		const { remainingArgs: devCommandArgs, overrides: devBackfillOverrides } = extractBackfillCliOptions(convexArgs);
+		const outputDir = cliOutputDir ?? config.outputDir;
+		const debug = cliDebug || config.dev.debug;
+		const generateApi = config.api;
+		const generateAuth = config.auth;
+		const convexDevArgs = [...config.dev.convexArgs, ...devCommandArgs];
+		const devBackfillConfig = resolveBackfillConfig(config.dev.aggregateBackfill, devBackfillOverrides);
+		const { functionsDir } = getConvexConfigFn(outputDir);
+		const schemaPath = join(functionsDir, "schema.ts");
+		const deploymentArgs = extractRunDeploymentArgs(convexDevArgs);
+		if (!deps) try {
+			ensureConvexGitignoreEntryFn(process.cwd());
+		} catch (error) {
+			console.warn(`⚠️  Failed to ensure .convex/ is ignored in .gitignore: ${error.message}`);
+		}
+		await generateMetaFn(outputDir, {
+			debug,
+			api: generateApi,
+			auth: generateAuth
+		});
 		const isTs = __filename.endsWith(".ts");
 		const watcherPath = isTs ? join(__dirname, "watcher.ts") : join(__dirname, "watcher.mjs");
 		const watcherProcess = execaFn(isTs ? "bun" : process.execPath, [watcherPath], {
@@ -160,40 +2578,131 @@ async function run(argv, deps) {
 			cwd: process.cwd(),
 			env: {
 				...process.env,
-				BETTER_CONVEX_OUTPUT_DIR: outputDir || "",
-				BETTER_CONVEX_DEBUG: debug ? "1" : ""
+				BETTER_CONVEX_API_OUTPUT_DIR: outputDir || "",
+				BETTER_CONVEX_DEBUG: debug ? "1" : "",
+				BETTER_CONVEX_GENERATE_API: generateApi ? "1" : "0",
+				BETTER_CONVEX_GENERATE_AUTH: generateAuth ? "1" : "0"
 			}
 		});
 		processes.push(watcherProcess);
 		const convexProcess = execaFn("node", [
 			realConvexPath,
 			"dev",
-			...convexArgs
+			...convexDevArgs
 		], {
 			stdio: "inherit",
 			cwd: process.cwd(),
 			reject: false
 		});
 		processes.push(convexProcess);
+		const backfillAbortController = new AbortController();
+		let schemaWatcher = null;
+		let schemaDebounceTimer = null;
+		let schemaBackfillInFlight = null;
+		let schemaBackfillQueued = false;
+		const maybeRunSchemaBackfill = async () => {
+			try {
+				if (await runDevSchemaBackfillIfNeeded({
+					execaFn,
+					realConvexPath,
+					backfillConfig: devBackfillConfig,
+					functionsDir,
+					deploymentArgs,
+					signal: backfillAbortController.signal
+				}) !== 0 && !backfillAbortController.signal.aborted) console.warn("⚠️  aggregateBackfill on schema update failed in dev (continuing without blocking).");
+			} catch (error) {
+				if (!backfillAbortController.signal.aborted) console.warn(`⚠️  aggregateBackfill on schema update errored in dev: ${error.message}`);
+			}
+		};
+		const queueSchemaBackfill = () => {
+			if (backfillAbortController.signal.aborted) return;
+			schemaBackfillQueued = true;
+			if (schemaBackfillInFlight) return;
+			schemaBackfillInFlight = (async () => {
+				while (schemaBackfillQueued && !backfillAbortController.signal.aborted) {
+					schemaBackfillQueued = false;
+					await maybeRunSchemaBackfill();
+				}
+			})().finally(() => {
+				schemaBackfillInFlight = null;
+			});
+		};
+		if (devBackfillConfig.enabled !== "off") (async () => {
+			try {
+				if (await runAggregateBackfillFlow({
+					execaFn,
+					realConvexPath,
+					backfillConfig: devBackfillConfig,
+					mode: "resume",
+					deploymentArgs,
+					signal: backfillAbortController.signal,
+					context: "dev"
+				}) !== 0 && !backfillAbortController.signal.aborted) console.warn("⚠️  aggregateBackfill kickoff failed in dev (continuing without blocking).");
+			} catch (error) {
+				if (!backfillAbortController.signal.aborted) console.warn(`⚠️  aggregateBackfill kickoff errored in dev: ${error.message}`);
+			}
+		})();
+		if (enableDevSchemaWatch && devBackfillConfig.enabled !== "off" && fs.existsSync(schemaPath)) {
+			const { watch } = await import("chokidar");
+			const watchedSchema = watch(schemaPath, { ignoreInitial: true });
+			schemaWatcher = watchedSchema;
+			watchedSchema.on("change", () => {
+				if (schemaDebounceTimer) clearTimeout(schemaDebounceTimer);
+				schemaDebounceTimer = setTimeout(() => {
+					queueSchemaBackfill();
+				}, 200);
+			}).on("error", (error) => {
+				if (!backfillAbortController.signal.aborted) console.warn(`⚠️  schema watch error (aggregate backfill): ${error.message}`);
+			});
+		}
 		process.on("exit", cleanup);
 		process.on("SIGINT", () => {
+			backfillAbortController.abort();
+			if (schemaDebounceTimer) clearTimeout(schemaDebounceTimer);
+			schemaWatcher?.close();
 			cleanup();
 			process.exit(0);
 		});
 		process.on("SIGTERM", () => {
+			backfillAbortController.abort();
+			if (schemaDebounceTimer) clearTimeout(schemaDebounceTimer);
+			schemaWatcher?.close();
 			cleanup();
 			process.exit(0);
 		});
 		const result = await Promise.race([watcherProcess.catch(() => ({ exitCode: 1 })), convexProcess]);
+		backfillAbortController.abort();
+		if (schemaDebounceTimer) clearTimeout(schemaDebounceTimer);
+		await schemaWatcher?.close();
 		cleanup();
 		return result.exitCode ?? 0;
 	}
 	if (command === "codegen") {
-		await generateMetaFn(outputDir, { debug });
+		const config = loadBetterConvexConfigFn(configPath);
+		const outputDir = cliOutputDir ?? config.outputDir;
+		const debug = cliDebug || config.codegen.debug;
+		const convexCodegenArgs = [...config.codegen.convexArgs, ...convexArgs];
+		const scope = cliScope ?? config.codegen.scope;
+		if (scope) await generateMetaFn(outputDir, {
+			debug,
+			scope
+		});
+		else {
+			const derivedScope = deriveScopeFromToggles(config.api, config.auth);
+			if (derivedScope) await generateMetaFn(outputDir, {
+				debug,
+				scope: derivedScope
+			});
+			else await generateMetaFn(outputDir, {
+				debug,
+				api: config.api,
+				auth: config.auth
+			});
+		}
 		return (await execaFn("node", [
 			realConvexPath,
 			"codegen",
-			...convexArgs
+			...convexCodegenArgs
 		], {
 			stdio: "inherit",
 			cwd: process.cwd()
@@ -218,6 +2727,85 @@ async function run(argv, deps) {
 			reject: false
 		})).exitCode ?? 0;
 	}
+	if (command === "analyze") return runAnalyzeFn(restArgs);
+	if (command === "reset") {
+		const { confirmed, beforeHook, afterHook, remainingArgs: resetCommandArgs } = extractResetCliOptions(convexArgs);
+		if (!confirmed) throw new Error("`better-convex reset` is destructive. Re-run with `--yes`.");
+		const deploymentArgs = extractRunDeploymentArgs([...loadBetterConvexConfigFn(configPath).deploy.convexArgs, ...resetCommandArgs]);
+		const runOptionalHook = async (functionName) => {
+			if (!functionName) return 0;
+			return (await runConvexFunction(execaFn, realConvexPath, functionName, {}, deploymentArgs)).exitCode;
+		};
+		const beforeExitCode = await runOptionalHook(beforeHook);
+		if (beforeExitCode !== 0) return beforeExitCode;
+		const resetResult = await runConvexFunction(execaFn, realConvexPath, "generated/server:reset", {}, deploymentArgs);
+		if (resetResult.exitCode !== 0) return resetResult.exitCode;
+		const backfillExitCode = await runAggregateBackfillFlow({
+			execaFn,
+			realConvexPath,
+			backfillConfig: {
+				enabled: "on",
+				wait: true,
+				batchSize: 1e3,
+				pollIntervalMs: 1e3,
+				timeoutMs: 9e5,
+				strict: false
+			},
+			mode: "resume",
+			deploymentArgs,
+			context: "aggregate"
+		});
+		if (backfillExitCode !== 0) return backfillExitCode;
+		return runOptionalHook(afterHook);
+	}
+	if (command === "deploy") {
+		const config = loadBetterConvexConfigFn(configPath);
+		const { remainingArgs: deployCommandArgs, overrides: deployBackfillOverrides } = extractBackfillCliOptions(convexArgs);
+		const deployArgs = [...config.deploy.convexArgs, ...deployCommandArgs];
+		const deployResult = await execaFn("node", [
+			realConvexPath,
+			"deploy",
+			...deployArgs
+		], {
+			stdio: "inherit",
+			cwd: process.cwd(),
+			reject: false
+		});
+		if ((deployResult.exitCode ?? 1) !== 0) return deployResult.exitCode ?? 1;
+		return runAggregateBackfillFlow({
+			execaFn,
+			realConvexPath,
+			backfillConfig: resolveBackfillConfig(config.deploy.aggregateBackfill, deployBackfillOverrides),
+			mode: "resume",
+			deploymentArgs: extractRunDeploymentArgs(deployArgs),
+			context: "deploy"
+		});
+	}
+	if (command === "aggregate") {
+		const subcommand = restArgs[0];
+		if (subcommand !== "rebuild" && subcommand !== "backfill" && subcommand !== "prune") throw new Error("Unknown aggregate command. Use: `better-convex aggregate backfill`, `better-convex aggregate rebuild`, or `better-convex aggregate prune`.");
+		const config = loadBetterConvexConfigFn(configPath);
+		const { remainingArgs: aggregateCommandArgs, overrides: aggregateBackfillOverrides } = extractBackfillCliOptions(restArgs.slice(1));
+		const aggregateArgs = [...config.deploy.convexArgs, ...aggregateCommandArgs];
+		const backfillConfig = {
+			...resolveBackfillConfig(config.deploy.aggregateBackfill, aggregateBackfillOverrides),
+			enabled: "on"
+		};
+		const deploymentArgs = extractRunDeploymentArgs(aggregateArgs);
+		if (subcommand === "prune") return runAggregatePruneFlow({
+			execaFn,
+			realConvexPath,
+			deploymentArgs
+		});
+		return runAggregateBackfillFlow({
+			execaFn,
+			realConvexPath,
+			backfillConfig,
+			mode: subcommand === "rebuild" ? "rebuild" : "resume",
+			deploymentArgs,
+			context: "aggregate"
+		});
+	}
 	return (await execaFn("node", [
 		realConvexPath,
 		command,
@@ -243,4 +2831,4 @@ if (isEntryPoint(process.argv[1], __filename)) run(process.argv.slice(2)).then((
 });
 
 //#endregion
-export { isEntryPoint, parseArgs, run };
+export { ensureConvexGitignoreEntry, getAggregateBackfillDeploymentKey, getDevAggregateBackfillStatePath, isEntryPoint, parseArgs, run };