next-evolve 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Velocinator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# next-evolve
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Self-improving Next.js sites: server-side variants with no flicker, measured in your own Postgres. Needs an Evolve Cloud account.
+
+> Alpha.
+
+## Setup
+
+```sh
+npx next-evolve init --routes "/ /pricing"   # add --dry-run to see the diff first
+npx next-evolve doctor                       # checks env, key, DB, bundle, proxy, pages, cloud → app
+```
+
+`init` installs the package, connects to your site (secret key and webhook secret from the dashboard), sets up the database, and writes the config, route handler, proxy, layout script, instrumentation and `prebuild` hook. Static-mode pages move under `app/[evolve]/` and get wrapped with `withEvolve()`; when that isn't safe (a top-level `[slug]`, `force-dynamic`, a `"use client"` page…) the route stays in dynamic mode and `init` says why. It never overwrites your `.env.local` lines, and a re-run changes nothing. `--yes` skips every prompt.
+
+Other commands: `migrate`, `pull`, `push`, `connect --test [--app-url]`, `aggregate`. The sections below describe what `init` writes.
+
+## Database
+
+Raw events (exposures, goal events, identities) stay in **your** Postgres (≥ 14), in a separate `evolve` schema. Evolve Cloud only ever receives aggregate counts.
+
+```sh
+EVOLVE_DATABASE_URL=postgres://… npx next-evolve migrate
+```
+
+Use the pooled URL on serverless hosts (e.g. Neon's `-pooler` host).
+
+## Goals
+
+```ts
+// evolve.goals.ts
+import { defineGoals } from "next-evolve/config";
+
+export default defineGoals({
+  cta_click: { event: "cta_click", window: "1d" },
+  signup_page: { pageview: "/signup", window: "1d" },
+  paid: {
+    event: "subscription_started",
+    source: "stripe",
+    window: "30d",
+    value: (e) => e.props.amount as number,
+  },
+});
+```
+
+Function values run in your app when the event is written; only `{ kind: "local-fn" }` is sent to the cloud.
+
+## Routes and beacon
+
+```ts
+// app/api/evolve/[...evolve]/route.ts
+import { createEvolveHandler } from "next-evolve/server";
+import evolveConfig from "@/evolve.config";
+import goals from "@/evolve.goals";
+
+export const { GET, POST } = createEvolveHandler({ config: evolveConfig, goals });
+export const maxDuration = 60;
+```
+
+Put `<EvolveScript />` (from `next-evolve/client`) in the root layout. It sends page views, exposures and clicks on `[data-evolve-goal]` elements (forms: on submit) to `/api/evolve/collect` on your own origin.
+
+## Tracking
+
+```ts
+import { evolve } from "next-evolve/server";
+
+await evolve.track("project_created", { userId: user.id });
+await evolve.identify(user.id); // links the visitor's evolve_id cookie; first link wins
+```
+
+In the browser: `import { track, identify } from "next-evolve/client"`.
+
+### Server-to-server events
+
+`POST /api/evolve/track` with `Authorization: Bearer $EVOLVE_TRACK_SECRET` and `{ "events": [{ "name", "userId"?, "anonId"?, "value"?, "props"?, "source"?, "ts"?, "dedupeKey"? }] }` (≤ 500 events). Unset secret → 404; wrong bearer → 401.
+
+### Stripe recipe
+
+Call `evolve.track` from your own Stripe webhook handler, after you verify the signature:
+
+```ts
+// app/api/stripe/route.ts
+import { evolve } from "next-evolve/server";
+
+if (event.type === "invoice.paid") {
+  const invoice = event.data.object;
+  await evolve.track("subscription_started", {
+    userId: invoice.metadata.userId,
+    source: "stripe",
+    props: { amount: invoice.amount_paid / 100 },
+    dedupeKey: event.id, // Stripe retries: stored once
+  });
+}
+```
+
+## Aggregation
+
+Evolve Cloud never reads your database. It sends a signed request to `POST /api/evolve/aggregate` (verified with `EVOLVE_WEBHOOK_SECRET`), and your app answers with counts and sums per experiment × variant × goal × day, signed with the same secret. No visitor or user ids leave your app. Set `EVOLVE_SECRET_KEY`, `EVOLVE_WEBHOOK_SECRET` and `EVOLVE_DATABASE_URL`; the route needs `maxDuration = 60`.
+
+In local development the cloud can't reach `localhost`. Run the same request yourself:
+
+```sh
+npx next-evolve aggregate           # print the statistics
+npx next-evolve aggregate --upload  # and send them to Evolve Cloud
+```
+
+## Sync
+
+Your app keeps a signed copy of its configuration (the bundle) in memory and serves from it with no network call on the request path. It gets new bundles three ways:
+
+- **Polling:** every 60 s (5 s in dev), in the background.
+- **Webhook:** when you change an experiment, Evolve Cloud calls `POST /api/evolve/sync` (signed with `EVOLVE_WEBHOOK_SECRET`). The receiving instance pulls the new bundle within seconds. The webhook carries no configuration, so a forged call can at most cause one extra fetch.
+- **Build time:** add `"prebuild": "next-evolve pull"` to `package.json` and pass the result to the proxy, so a fresh instance serves the last bundle before its first fetch:
+
+```ts
+// proxy.ts
+import { createEvolveProxy } from "next-evolve/proxy";
+import buildBundle from "./.evolve/bundle.generated";
+import evolveConfig from "./evolve.config";
+
+export const proxy = createEvolveProxy(evolveConfig, { buildBundle });
+```
+
+Add `.evolve/` to `.gitignore`. `pull` never fails the build: without a key or a reachable cloud it keeps the previous bundle or writes an empty one.
+
+**Long-running Node (`next start`, Docker):** call `registerEvolve()` from `instrumentation.ts`. It polls in the background and keeps the last bundle on disk (`os.tmpdir()`, or `EVOLVE_CACHE_DIR`), so a restart serves it even when the cloud is unreachable.
+
+**Vercel + Global Config (recommended on Vercel):** without it, a webhook reaches only the instance that receives it and the others catch up within 60 s. With a [Global Config](https://vercel.com/docs/edge-config) store, the sync route writes the bundle there and every instance picks it up within ~10 s. Set:
+
+| Var                       | Purpose                                 |
+| ------------------------- | --------------------------------------- |
+| `EVOLVE_GLOBAL_CONFIG`    | The store's connection string (read)    |
+| `EVOLVE_GLOBAL_CONFIG_ID` | The store id (`ecfg_…`), for writes     |
+| `EVOLVE_VERCEL_API_TOKEN` | A Vercel token that can write the store |
+| `EVOLVE_VERCEL_TEAM_ID`   | Optional, for team-owned stores         |
+
+Bundles read from Global Config are verified like any other. With an existing proxy that calls `applyEvolve`, `await evolveReady(evolveConfig)` first (a fresh instance waits ≤ 20 ms for one read).

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,12 @@
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+export { __exportAll };

package/dist/aggregate/attribution.d.ts

@@ -0,0 +1,40 @@
+import { Sql } from "../db/client.js";
+import { AggregateRow, SerializedGoal } from "@next-evolve/protocol";
+export type AttributionInput = {
+  experimentId: string;
+  /** Only exposures to these variants count. */
+  variants: readonly string[];
+  goalKey: string;
+  goal: SerializedGoal;
+  /** Upper bound for exposures and events (exclusive). */
+  asOf: Date;
+  /** Only units whose cohort day (UTC day of first exposure) is on/after this `YYYY-MM-DD`. */
+  cohortsFrom: string;
+};
+type RawRow = {
+  variant_id: string;
+  seg: string;
+  day: string;
+  n: number;
+  c: number;
+  s1: number;
+  s2: number;
+  mn: number;
+  mc: number;
+  ms1: number;
+  ms2: number;
+};
+/**
+ * The attribution query for one experiment × goal. An event counts for a unit
+ * when it falls in `[first exposure, first exposure + window)`, capped at
+ * `asOf`. A unit is mature when its whole window ended before `asOf`.
+ *
+ * - visitor unit: one unit per exposed anon id; events match on the anon id,
+ *   or on the linked user id (cross-device and server events).
+ * - user unit: identified exposures only, one unit per user at their earliest
+ *   exposure; events match on the user id or any of the user's anon ids.
+ */
+export declare function attributionQuery(sql: Sql, input: AttributionInput): import("postgres").PendingQuery<RawRow[]>;
+/** Runs the attribution query and returns protocol rows. */
+export declare function runAttribution(sql: Sql, input: AttributionInput): Promise<AggregateRow[]>;
+export {};

package/dist/aggregate/attribution.js

@@ -0,0 +1,115 @@
+import { parseWindowSeconds } from "@next-evolve/protocol";
+// src/aggregate/attribution.ts
+const NUMERIC_RE = "^\\s*-?(\\d{1,30}(\\.\\d{0,30})?|\\.\\d{1,30})([eE][-+]?\\d{1,2})?\\s*$";
+function numericText(sql, text) {
+	return sql`(case when ${text} ~ ${NUMERIC_RE} then (${text})::float8 end)`;
+}
+/** The event's value for this goal (null → conversion only). */
+function valueExpr(sql, key, goal) {
+	if (goal.kind === "pageview" || goal.value === null) return sql`e.value`;
+	if (goal.value.kind === "local-fn") return numericText(sql, sql`e.goal_values ->> ${key}::text`);
+	return numericText(sql, sql`e.props #>> string_to_array(${goal.value.path}::text, '.')`);
+}
+/** Which events count for this goal (window and unit join come from the caller). */
+function matchExpr(sql, goal) {
+	if (goal.kind === "pageview") return sql`e.name = '$pageview' and ${goal.path.endsWith("*") ? sql`starts_with(e.path, ${goal.path.slice(0, -1)}::text)` : sql`e.path = ${goal.path}::text`}`;
+	const source = goal.source === null ? sql`` : sql`and e.source = ${goal.source}::text`;
+	const where = goal.where === null ? sql`` : sql`and e.props @> (${JSON.stringify(goal.where)}::text)::jsonb`;
+	return sql`e.name = ${goal.event}::text ${source} ${where}`;
+}
+/**
+* The attribution query for one experiment × goal. An event counts for a unit
+* when it falls in `[first exposure, first exposure + window)`, capped at
+* `asOf`. A unit is mature when its whole window ended before `asOf`.
+*
+* - visitor unit: one unit per exposed anon id; events match on the anon id,
+*   or on the linked user id (cross-device and server events).
+* - user unit: identified exposures only, one unit per user at their earliest
+*   exposure; events match on the user id or any of the user's anon ids.
+*/
+function attributionQuery(sql, input) {
+	const windowSeconds = parseWindowSeconds(input.goal.window);
+	if (windowSeconds === null) throw new Error(`invalid goal window ${input.goal.window}`);
+	const asOf = input.asOf.toISOString();
+	const from = `${input.cohortsFrom}T00:00:00Z`;
+	const win = sql`make_interval(secs => ${windowSeconds}::int)`;
+	const asOfTs = sql`${asOf}::timestamptz`;
+	const val = valueExpr(sql, input.goalKey, input.goal);
+	const match = matchExpr(sql, input.goal);
+	const inWindow = sql`e.ts >= u.first_at and e.ts < least(u.first_at + ${win}, ${asOfTs})`;
+	const variants = sql`string_to_array(${input.variants.join(",")}::text, ',')`;
+	return sql`
+    with ${input.goal.unit === "visitor" ? sql`
+    u as (
+      select x.anon_id as unit, x.variant_id, x.first_at, coalesce(x.segment, 'main') as seg,
+             i.user_id, (x.first_at + ${win} <= ${asOfTs}) as mature
+      from evolve.exposures x
+      left join evolve.identities i on i.anon_id = x.anon_id
+      where x.experiment_id = ${input.experimentId}::text
+        and x.variant_id = any(${variants})
+        and x.first_at >= ${from}::timestamptz and x.first_at < ${asOfTs}),
+    hits as (
+      select u.unit, ${val} as v from u
+      join evolve.events e on e.anon_id = u.unit
+      where ${match} and ${inWindow}
+      union all
+      select u.unit, ${val} from u
+      join evolve.events e on e.user_id = u.user_id
+      where u.user_id is not null and (e.anon_id is null or e.anon_id <> u.unit)
+        and ${match} and ${inWindow})` : sql`
+    firsts as (
+      -- Earliest exposure per user over all cohorts, so a user exposed again on
+      -- another device never becomes a second unit in a later cohort.
+      select distinct on (i.user_id) i.user_id as unit, x.variant_id, x.first_at,
+             coalesce(x.segment, 'main') as seg
+      from evolve.exposures x
+      join evolve.identities i on i.anon_id = x.anon_id
+      where x.experiment_id = ${input.experimentId}::text and x.first_at < ${asOfTs}
+      order by i.user_id, x.first_at, x.anon_id),
+    u as (
+      select unit, variant_id, first_at, seg, (first_at + ${win} <= ${asOfTs}) as mature
+      from firsts
+      where variant_id = any(${variants}) and first_at >= ${from}::timestamptz),
+    hits as (
+      select u.unit, ${val} as v from u
+      join evolve.events e on e.user_id = u.unit
+      where ${match} and ${inWindow}
+      union all
+      select u.unit, ${val} from u
+      join evolve.identities ia on ia.user_id = u.unit
+      join evolve.events e on e.anon_id = ia.anon_id
+      where (e.user_id is null or e.user_id <> u.unit) and ${match} and ${inWindow})`},
+    per_unit as (select unit, sum(coalesce(v, 0)) as v from hits group by unit)
+    select u.variant_id, u.seg,
+      to_char((u.first_at at time zone 'UTC')::date, 'YYYY-MM-DD') as day,
+      count(*)::int as n,
+      count(p.unit)::int as c,
+      coalesce(sum(p.v), 0)::float8 as s1,
+      coalesce(sum(p.v * p.v), 0)::float8 as s2,
+      (count(*) filter (where u.mature))::int as mn,
+      (count(p.unit) filter (where u.mature))::int as mc,
+      coalesce(sum(p.v) filter (where u.mature), 0)::float8 as ms1,
+      coalesce(sum(p.v * p.v) filter (where u.mature), 0)::float8 as ms2
+    from u left join per_unit p on p.unit = u.unit
+    group by 1, 2, 3
+    order by 3, 1, 2`;
+}
+/** Runs the attribution query and returns protocol rows. */
+async function runAttribution(sql, input) {
+	return (await attributionQuery(sql, input)).map((r) => ({
+		exp: input.experimentId,
+		var: r.variant_id,
+		goal: input.goalKey,
+		seg: r.seg,
+		day: r.day,
+		n: r.n,
+		c: r.c,
+		s1: r.s1,
+		s2: r.s2,
+		mn: r.mn,
+		mc: r.mc,
+		ms1: r.ms1,
+		ms2: r.ms2
+	}));
+}
+export { attributionQuery, runAttribution };

package/dist/aggregate/run.d.ts

@@ -0,0 +1,21 @@
+import { Sql } from "../db/client.js";
+import { AggregateRequest, AggregateResponse } from "@next-evolve/protocol";
+export type RunAggregateOptions = {
+  /** Whole-request budget (spec: 25 s). */
+  maxMs: number;
+  /** Per-query cap (spec: 20 s). */
+  statementTimeoutMs: number;
+  sdkVersion: string;
+  now?: () => number;
+};
+export type RunAggregateResult = {
+  kind: "ok";
+  response: AggregateResponse;
+  cached: boolean;
+} | {
+  kind: "busy";
+  retryAfter: number;
+};
+/** Answer `429 { busy, retryAfter }` while another aggregate holds the lock. */
+export declare const BUSY_RETRY_AFTER_SECONDS = 30;
+export declare function runAggregate(sql: Sql, req: AggregateRequest, opts: RunAggregateOptions): Promise<RunAggregateResult>;

package/dist/aggregate/run.js

@@ -0,0 +1,139 @@
+import { runAttribution } from "./attribution.js";
+import { MAX_RESPONSE_ROWS } from "@next-evolve/protocol";
+import { createHash } from "node:crypto";
+// src/aggregate/run.ts
+/** Answer `429 { busy, retryAfter }` while another aggregate holds the lock. */
+const BUSY_RETRY_AFTER_SECONDS = 30;
+/** Below this much budget left, don't start another query. */
+const MIN_QUERY_MS = 500;
+const QUERY_CANCELED = "57014";
+/** Stored responses are replayed for this long (spec §9.3). */
+const RUN_TTL = "24 hours";
+async function storedResponse(sql, requestId) {
+	const [hit] = await sql`
+    select response from evolve.aggregate_runs
+    where request_id = ${requestId} and status = 'done'
+      and received_at > now() - ${RUN_TTL}::interval`;
+	return hit?.response ?? null;
+}
+async function runAggregate(sql, req, opts) {
+	const now = opts.now ?? Date.now;
+	const started = now();
+	const cached = await storedResponse(sql, req.requestId);
+	if (cached) return {
+		kind: "ok",
+		response: cached,
+		cached: true
+	};
+	const conn = await sql.reserve();
+	let locked = false;
+	try {
+		const [l] = await conn`
+      select pg_try_advisory_lock(hashtext('evolve.aggregate')) as ok`;
+		locked = Boolean(l?.ok);
+		if (!locked) return {
+			kind: "busy",
+			retryAfter: 30
+		};
+		const raced = await storedResponse(conn, req.requestId);
+		if (raced) return {
+			kind: "ok",
+			response: raced,
+			cached: true
+		};
+		const deadline = started + opts.maxMs;
+		const asOf = new Date(req.asOf);
+		const rows = [];
+		const errors = [];
+		const remaining = [];
+		for (const exp of req.experiments) {
+			if (remaining.length) {
+				remaining.push(exp.id);
+				continue;
+			}
+			const expRows = [];
+			const expErrors = [];
+			let outOfBudget = false;
+			for (const g of exp.goals) {
+				const left = deadline - now();
+				if (left < MIN_QUERY_MS) {
+					outOfBudget = true;
+					break;
+				}
+				const timeout = Math.floor(Math.min(opts.statementTimeoutMs, left));
+				await conn.unsafe(`set statement_timeout = ${timeout}`);
+				try {
+					expRows.push(...await runAttribution(conn, {
+						experimentId: exp.id,
+						variants: exp.variants,
+						goalKey: g.key,
+						goal: g.def,
+						asOf,
+						cohortsFrom: exp.cohortsFrom
+					}));
+				} catch (e) {
+					const code = e.code;
+					if (code === QUERY_CANCELED && now() >= deadline - MIN_QUERY_MS) {
+						outOfBudget = true;
+						break;
+					}
+					expErrors.push({
+						exp: exp.id,
+						goal: g.key,
+						message: code === QUERY_CANCELED ? "statement timeout" : errorMessage(e)
+					});
+				}
+			}
+			if (outOfBudget || rows.length + expRows.length > MAX_RESPONSE_ROWS) {
+				remaining.push(exp.id);
+				continue;
+			}
+			rows.push(...expRows);
+			errors.push(...expErrors);
+		}
+		await conn.unsafe("set statement_timeout = 0");
+		const usage = req.usageFrom ? (await conn`
+            select to_char(day, 'YYYY-MM-DD') as day, tested_pageviews::text as n
+            from evolve.usage_daily where day >= ${req.usageFrom}::date order by day`).map((u) => ({
+			day: u.day,
+			testedPageviews: Number(u.n)
+		})) : [];
+		const response = {
+			pv: req.pv,
+			requestId: req.requestId,
+			site: req.site,
+			asOf: req.asOf,
+			sdk: opts.sdkVersion,
+			mode: req.mode,
+			durationMs: Math.max(0, Math.round(now() - started)),
+			partial: remaining.length > 0,
+			remaining,
+			rows,
+			usage,
+			errors
+		};
+		const body = JSON.stringify(response);
+		await conn`
+      insert into evolve.aggregate_runs
+        (request_id, received_at, mode, status, duration_ms, response_hash, response)
+      values (${req.requestId}, ${new Date(started)}, ${req.mode}, 'done', ${response.durationMs},
+        ${createHash("sha256").update(body).digest("hex")}, (${body}::text)::jsonb)
+      on conflict (request_id) do nothing`;
+		await conn`delete from evolve.aggregate_runs where received_at < now() - ${RUN_TTL}::interval`;
+		return {
+			kind: "ok",
+			response,
+			cached: false
+		};
+	} finally {
+		if (locked) {
+			await conn.unsafe("set statement_timeout = 0").catch(() => {});
+			await conn`select pg_advisory_unlock(hashtext('evolve.aggregate'))`.catch(() => {});
+		}
+		conn.release();
+	}
+}
+function errorMessage(e) {
+	return String(e instanceof Error ? e.message : e).slice(0, 500);
+}
+export { BUSY_RETRY_AFTER_SECONDS, runAggregate };

package/dist/cli/aggregate.d.ts

@@ -0,0 +1,9 @@
+type Env = Record<string, string | undefined>;
+export type AggregateCommandDeps = {
+  env: Env;
+  fetch?: typeof fetch;
+  out?: (s: string) => void;
+  err?: (s: string) => void;
+};
+export declare function aggregateCommand(args: string[], deps: AggregateCommandDeps): Promise<number>;
+export {};

package/dist/cli/aggregate.js

@@ -0,0 +1,104 @@
+import { runAggregate } from "../aggregate/run.js";
+import { sdkVersion } from "../cloud/manifest.js";
+import { createSql } from "../db/client.js";
+import "../store/runtime.js";
+import { SIGNATURE_HEADER, aggregateRequestSchema, isSupportedProtocol, parseSecretKey, signBody } from "@next-evolve/protocol";
+// src/cli/aggregate.ts
+async function aggregateCommand(args, deps) {
+	const { env } = deps;
+	const out = deps.out ?? ((s) => process.stdout.write(`${s}\n`));
+	const err = deps.err ?? ((s) => console.error(s));
+	const doFetch = deps.fetch ?? fetch;
+	const upload = args.includes("--upload");
+	const key = env.EVOLVE_SECRET_KEY;
+	const secret = env.EVOLVE_WEBHOOK_SECRET;
+	const dbUrl = env.EVOLVE_DATABASE_URL;
+	const site = parseSecretKey(key ?? "")?.siteId;
+	const missing = [
+		!site && "EVOLVE_SECRET_KEY",
+		!dbUrl && "EVOLVE_DATABASE_URL",
+		upload && !secret && "EVOLVE_WEBHOOK_SECRET"
+	].filter(Boolean);
+	if (missing.length) {
+		err(`next-evolve aggregate: set ${missing.join(", ")}`);
+		return 1;
+	}
+	const cloud = env.EVOLVE_CLOUD_URL ?? "https://api.evolveab.com";
+	const auth = { authorization: `Bearer ${key}` };
+	let request;
+	try {
+		const res = await doFetch(new URL("/v1/aggregates/request", cloud), {
+			method: "POST",
+			headers: auth
+		});
+		if (res.status === 404) {
+			out("Nothing to aggregate: no running experiments.");
+			return 0;
+		}
+		if (!res.ok) {
+			err(`next-evolve aggregate: the cloud answered ${res.status} for the request`);
+			return 1;
+		}
+		const body = await res.json();
+		if (!isSupportedProtocol(body.request?.pv)) {
+			err("next-evolve aggregate: unsupported protocol version; upgrade next-evolve");
+			return 1;
+		}
+		const parsed = aggregateRequestSchema.safeParse(body.request);
+		if (!parsed.success || parsed.data.site !== site) {
+			err("next-evolve aggregate: the cloud sent an invalid request");
+			return 1;
+		}
+		request = parsed.data;
+	} catch (e) {
+		err(`next-evolve aggregate: can't reach ${cloud} (${e instanceof Error ? e.message : e})`);
+		return 1;
+	}
+	const sql = createSql(dbUrl, { max: 1 });
+	let result;
+	try {
+		result = await runAggregate(sql, request, {
+			maxMs: 12e4,
+			statementTimeoutMs: 6e4,
+			sdkVersion: sdkVersion()
+		});
+	} catch (e) {
+		err(`next-evolve aggregate: database error (${e instanceof Error ? e.message : e})`);
+		return 1;
+	} finally {
+		await sql.end({ timeout: 5 });
+	}
+	if (result.kind === "busy") {
+		err("next-evolve aggregate: another aggregation is running; try again in 30 s");
+		return 1;
+	}
+	const r = result.response;
+	const summary = `${r.rows.length} rows for ${request.experiments.length} experiment(s) in ${r.durationMs} ms${r.partial ? `, partial (remaining: ${r.remaining.join(", ")})` : ""}${r.errors.length ? `, ${r.errors.length} error(s)` : ""}`;
+	if (!upload) {
+		out(JSON.stringify(r, null, 2));
+		err(summary);
+		return 0;
+	}
+	const body = JSON.stringify(r);
+	try {
+		const res = await doFetch(new URL("/v1/aggregates", cloud), {
+			method: "POST",
+			headers: {
+				...auth,
+				"content-type": "application/json",
+				[SIGNATURE_HEADER]: signBody(secret, body)
+			},
+			body
+		});
+		if (!res.ok) {
+			err(`next-evolve aggregate: upload failed (${res.status} ${await res.text()})`);
+			return 1;
+		}
+	} catch (e) {
+		err(`next-evolve aggregate: upload failed (${e instanceof Error ? e.message : e})`);
+		return 1;
+	}
+	out(`Uploaded ${summary}.`);
+	return 0;
+}
+export { aggregateCommand };

package/dist/cli/args.d.ts

@@ -0,0 +1,12 @@
+export type FlagSpec = Record<string, {
+  type: "string" | "boolean";
+  short?: string;
+}>;
+/** Parses `--flag value` / `--flag`; unknown flags are an error (returned, not thrown). */
+export declare function parseFlags<S extends FlagSpec>(args: string[], spec: S): {
+  ok: true;
+  flags: { [K in keyof S]?: S[K]["type"] extends "boolean" ? boolean : string; };
+} | {
+  ok: false;
+  error: string;
+};

package/dist/cli/args.js

@@ -0,0 +1,23 @@
+import { parseArgs } from "node:util";
+// src/cli/args.ts
+/** Parses `--flag value` / `--flag`; unknown flags are an error (returned, not thrown). */
+function parseFlags(args, spec) {
+	try {
+		const { values } = parseArgs({
+			args,
+			options: spec,
+			strict: true,
+			allowPositionals: false
+		});
+		return {
+			ok: true,
+			flags: values
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			error: e instanceof Error ? e.message : String(e)
+		};
+	}
+}
+export { parseFlags };