@ogygia/cli 0.0.0-stage → 0.11.0

package/dist/perf/bisect.js

@@ -0,0 +1,69 @@
+// src/perf/bisect.ts
+async function bisect(opts) {
+	const { commits, good_value, bad_value } = opts;
+	const margin = opts.margin ?? .5;
+	const bar = good_value + (bad_value - good_value) * margin;
+	const steps = [];
+	const skipped = [];
+	if (bad_value <= good_value) return {
+		culprit: null,
+		last_good: null,
+		good_value,
+		bad_value,
+		bar,
+		steps,
+		skipped
+	};
+	let lo = -1;
+	let hi = commits.length - 1;
+	const known = /* @__PURE__ */ new Map();
+	if (hi >= 0) known.set(commits[hi], true);
+	while (hi - lo > 1) {
+		const mid = lo + Math.floor((hi - lo) / 2);
+		let pick = -1;
+		for (let d = 0; mid - d > lo || mid + d < hi; d++) {
+			if (mid + d < hi && !skipped.includes(commits[mid + d])) {
+				pick = mid + d;
+				break;
+			}
+			if (mid - d > lo && !skipped.includes(commits[mid - d])) {
+				pick = mid - d;
+				break;
+			}
+		}
+		if (pick === -1) break;
+		const sha = commits[pick];
+		const t = Date.now();
+		let value = null;
+		try {
+			value = await opts.measure(sha);
+		} catch {
+			value = null;
+		}
+		const step = {
+			sha,
+			value,
+			bad: value !== null && value > bar,
+			ms: Date.now() - t
+		};
+		steps.push(step);
+		opts.on_step?.(step);
+		if (value === null) {
+			skipped.push(sha);
+			continue;
+		}
+		known.set(sha, step.bad);
+		if (step.bad) hi = pick;
+		else lo = pick;
+	}
+	return {
+		culprit: hi >= 0 && hi < commits.length ? commits[hi] : null,
+		last_good: lo >= 0 ? commits[lo] : null,
+		good_value,
+		bad_value,
+		bar,
+		steps,
+		skipped
+	};
+}
+export { bisect };

package/dist/perf/cli.js

@@ -0,0 +1,221 @@
+import { measure } from "./measure.js";
+import { verdict } from "./compare.js";
+import { markdown, summary } from "./report.js";
+import { bisect } from "./bisect.js";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { execSync, spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+// src/perf/cli.ts
+/**
+* `ogygia perf` and `ogygia bisect` — the runners around the pure modules. Loaded by the CLI on
+* demand (a sibling in dist), so the CLI bundle stays small.
+*
+*   ogygia perf --url http://127.0.0.1:4173 --pages /,/docs [--runs 5] [--key $SECRET]
+*               [--baseline perf-baseline.json] [--budget budget.json] [--out perf-snapshot.json]
+*               [--md perf-comment.md] [--label "$GITHUB_SHA"] [--no-fail]
+*
+*   ogygia bisect --good <sha> --bad <sha> --page /slow --build "pnpm build" --start "node build"
+*                 --url http://127.0.0.1:3000 [--key $SECRET] [--runs 3] [--margin 0.5] [--ready 60000]
+*/
+function arg(argv, name) {
+	const i = argv.indexOf(name);
+	if (i === -1) return void 0;
+	const v = argv[i + 1];
+	return v && !v.startsWith("--") ? v : "";
+}
+const has = (argv, name) => argv.includes(name);
+/** A number flag: its value whenever it parses, `0` included (`Number(v) || d` turns a real 0 into
+*  the default); `fallback` when the flag is absent, empty or not a number. */
+function number_arg(argv, name, fallback) {
+	const raw = arg(argv, name);
+	if (raw === void 0 || raw.trim() === "") return fallback;
+	const n = Number(raw);
+	return Number.isFinite(n) ? n : fallback;
+}
+function read_json(file) {
+	if (!file || !existsSync(file)) return null;
+	return JSON.parse(readFileSync(file, "utf8"));
+}
+async function runPerf(argv) {
+	const url = arg(argv, "--url");
+	const pages = (arg(argv, "--pages") ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+	const pages_file = arg(argv, "--pages-file");
+	if (pages_file) {
+		const list = read_json(pages_file);
+		if (Array.isArray(list)) pages.push(...list);
+		else if (list?.pages) pages.push(...list.pages);
+	}
+	if (!url || !pages.length) {
+		process.stderr.write("ogygia perf: --url <origin> and --pages /a,/b (or --pages-file) are required\n");
+		return 2;
+	}
+	const runs = Number(arg(argv, "--runs")) || 5;
+	const key = arg(argv, "--key") ?? process.env.OGYGIA_PROFILER_SECRET;
+	const base = arg(argv, "--base");
+	const label = arg(argv, "--label");
+	const budget = read_json(arg(argv, "--budget")) ?? {};
+	const baseline = read_json(arg(argv, "--baseline"));
+	process.stdout.write(`ogygia perf · ${pages.length} page${pages.length === 1 ? "" : "s"} × ${runs} runs on ${url}${baseline ? " · against the baseline" : " · no baseline (caps only)"}\n`);
+	let snap;
+	try {
+		snap = await measure({
+			url,
+			pages,
+			runs,
+			key,
+			base,
+			label,
+			on_page: (p) => process.stdout.write(`  measured ${p.page}: ${p.render_p50.toFixed(1)} ms\n`)
+		});
+	} catch (e) {
+		process.stderr.write(`ogygia perf: ${e instanceof Error ? e.message : String(e)}\n`);
+		return 2;
+	}
+	const out = arg(argv, "--out");
+	if (out) writeFileSync(out, JSON.stringify(snap, null, 2));
+	const v = verdict(baseline, snap, budget);
+	const md = arg(argv, "--md");
+	if (md) writeFileSync(md, markdown(v, { title: label ? `Performance (${label})` : "Performance" }));
+	process.stdout.write(summary(v) + "\n");
+	if (out) process.stdout.write(`snapshot: ${out}${md ? ` · comment: ${md}` : ""}\n`);
+	return v.ok || has(argv, "--no-fail") ? 0 : 1;
+}
+function sh(cmd, cwd, timeout_ms) {
+	execSync(cmd, {
+		cwd,
+		stdio: "inherit",
+		timeout: timeout_ms,
+		env: {
+			...process.env,
+			CI: "1"
+		}
+	});
+}
+/** Start a server command, wait until `url` answers (or `ready_ms`), return a stopper. */
+async function serve(cmd, cwd, url, ready_ms) {
+	const child = spawn(cmd, {
+		cwd,
+		shell: true,
+		stdio: "ignore",
+		detached: true,
+		env: { ...process.env }
+	});
+	const stop = () => {
+		try {
+			if (child.pid) process.kill(-child.pid, "SIGTERM");
+		} catch {}
+	};
+	const until = Date.now() + ready_ms;
+	while (Date.now() < until) {
+		try {
+			if ((await fetch(url, { redirect: "manual" })).status < 500) return stop;
+		} catch {}
+		await new Promise((r) => setTimeout(r, 500));
+	}
+	stop();
+	throw new Error(`server did not answer at ${url} within ${ready_ms} ms`);
+}
+async function runBisect(argv) {
+	const good = arg(argv, "--good");
+	const bad = arg(argv, "--bad") ?? "HEAD";
+	const page = arg(argv, "--page");
+	const build = arg(argv, "--build");
+	const start = arg(argv, "--start");
+	const url = arg(argv, "--url");
+	if (!good || !page || !build || !start || !url) {
+		process.stderr.write("ogygia bisect: --good <sha> --page /x --build \"<cmd>\" --start \"<cmd>\" --url <origin> are required (--bad defaults to HEAD)\n");
+		return 2;
+	}
+	const runs = Number(arg(argv, "--runs")) || 3;
+	const key = arg(argv, "--key") ?? process.env.OGYGIA_PROFILER_SECRET;
+	const margin = number_arg(argv, "--margin", .5);
+	const ready_ms = Number(arg(argv, "--ready")) || 6e4;
+	const build_ms = Number(arg(argv, "--build-timeout")) || 9e5;
+	const repo = process.cwd();
+	const commits = execSync(`git rev-list --reverse ${good}..${bad}`, {
+		cwd: repo,
+		encoding: "utf8"
+	}).trim().split("\n").filter(Boolean);
+	if (!commits.length) {
+		process.stderr.write(`ogygia bisect: no commits between ${good} and ${bad}\n`);
+		return 2;
+	}
+	process.stdout.write(`ogygia bisect · ${commits.length} commits between ${good.slice(0, 7)} and ${bad.slice(0, 7)} · page ${page}\n`);
+	const worktree = mkdtempSync(path.join(tmpdir(), "ogygia-bisect-"));
+	const running = { stop: null };
+	const measure_sha = async (sha) => {
+		try {
+			const dir = path.join(worktree, sha.slice(0, 12));
+			if (!existsSync(dir)) sh(`git worktree add --detach "${dir}" ${sha}`, repo, 6e4);
+			try {
+				sh(build, dir, build_ms);
+			} catch {
+				process.stdout.write(`  ${sha.slice(0, 7)}: build failed — skipped\n`);
+				return null;
+			}
+			running.stop = await serve(start, dir, url, ready_ms);
+			try {
+				return (await measure({
+					url,
+					pages: [page],
+					runs,
+					key
+				})).pages[0].render_p50;
+			} finally {
+				running.stop();
+				running.stop = null;
+			}
+		} catch (e) {
+			process.stdout.write(`  ${sha.slice(0, 7)}: ${e instanceof Error ? e.message : String(e)} — skipped\n`);
+			return null;
+		} finally {
+			try {
+				sh(`git worktree remove --force "${path.join(worktree, sha.slice(0, 12))}"`, repo, 6e4);
+			} catch {}
+		}
+	};
+	try {
+		const good_sha = execSync(`git rev-parse ${good}`, {
+			cwd: repo,
+			encoding: "utf8"
+		}).trim();
+		const bad_sha = execSync(`git rev-parse ${bad}`, {
+			cwd: repo,
+			encoding: "utf8"
+		}).trim();
+		process.stdout.write(`  measuring the ends…\n`);
+		const good_value = await measure_sha(good_sha);
+		const bad_value = await measure_sha(bad_sha);
+		if (good_value === null || bad_value === null) {
+			process.stderr.write("ogygia bisect: could not measure the good or the bad end\n");
+			return 2;
+		}
+		process.stdout.write(`  good ${good_value.toFixed(1)} ms · bad ${bad_value.toFixed(1)} ms\n`);
+		const result = await bisect({
+			commits,
+			good_value,
+			bad_value,
+			margin,
+			measure: measure_sha,
+			on_step: (s) => process.stdout.write(`  ${s.sha.slice(0, 7)}: ${s.value === null ? "skipped" : `${s.value.toFixed(1)} ms → ${s.bad ? "bad" : "good"}`} (${Math.round(s.ms / 1e3)} s)\n`)
+		});
+		if (!result.culprit) {
+			process.stdout.write(`no commit in the range crossed the bar (${result.bar.toFixed(1)} ms): the regression is not between these commits, or it is noise\n`);
+			return 1;
+		}
+		const subject = execSync(`git log -1 --format=%s ${result.culprit}`, {
+			cwd: repo,
+			encoding: "utf8"
+		}).trim();
+		process.stdout.write(`\nfirst bad commit: ${result.culprit.slice(0, 7)} — ${subject}\n${result.last_good ? `last good: ${result.last_good.slice(0, 7)}\n` : ""}bar: ${result.bar.toFixed(1)} ms · ${result.steps.length} steps${result.skipped.length ? ` · skipped ${result.skipped.length}` : ""}\n`);
+		return 0;
+	} finally {
+		running.stop?.();
+		rmSync(worktree, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+export { number_arg, runBisect, runPerf };

package/dist/perf/compare.js

@@ -0,0 +1,166 @@
+// src/perf/compare.ts
+const DEFAULT_BUDGET = {
+	render_pct: 8,
+	render_floor_ms: 5,
+	busy_pct: 15,
+	component_pct: 25,
+	seed_kb: 20,
+	props_kb: 30,
+	islands_js_kb: 30,
+	cold_extra_ms: 100,
+	fail_on: []
+};
+const r1 = (n) => Math.round(n * 10) / 10;
+/** The budget for one page: defaults, the top level, then the page's overrides. */
+function budget_for(page, budget) {
+	const { pages, ...top } = budget;
+	const over = pages?.[page] ?? {};
+	return {
+		...DEFAULT_BUDGET,
+		render_max_ms: Infinity,
+		seed_max_kb: Infinity,
+		islands_js_max_kb: Infinity,
+		...strip(top),
+		...strip(over)
+	};
+}
+const strip = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
+function verdict(baseline, current, budget = {}) {
+	const base_pages = new Map((baseline?.pages ?? []).map((p) => [p.page, p]));
+	const pages = current.pages.map((cur) => judge(cur, base_pages.get(cur.page) ?? null, budget_for(cur.page, budget)));
+	const measured = new Set(current.pages.map((p) => p.page));
+	const missing = [...base_pages.keys()].filter((p) => !measured.has(p));
+	const failures = pages.flatMap((p) => p.failures.map((f) => `${p.page}: ${f}`));
+	return {
+		ok: failures.length === 0,
+		pages,
+		missing,
+		failures
+	};
+}
+function judge(cur, base, b) {
+	const rows = [];
+	const failures = [];
+	const row = (metric, unit, c, bv, judge_) => {
+		const delta = bv === null ? null : r1(c - bv);
+		const pct = bv === null || bv === 0 ? null : r1((c - bv) / bv * 100);
+		const j = judge_(delta, c);
+		rows.push({
+			metric,
+			unit,
+			base: bv,
+			cur: r1(c),
+			delta,
+			pct,
+			limit: j.limit,
+			over: j.over
+		});
+		if (j.over) failures.push(j.why ?? `${metric} over budget`);
+	};
+	const grew = (delta, base_v, pct, floor) => delta !== null && base_v !== null && delta > floor && delta > base_v * pct / 100;
+	row("render (median)", "ms", cur.render_p50, base?.render_p50 ?? null, (d, c) => {
+		const rel = grew(d, base?.render_p50 ?? null, b.render_pct, b.render_floor_ms);
+		const cap = c > b.render_max_ms;
+		return {
+			over: rel || cap,
+			limit: `+${b.render_pct}% (≥ ${b.render_floor_ms} ms)${Number.isFinite(b.render_max_ms) ? `, max ${b.render_max_ms} ms` : ""}`,
+			why: cap ? `render ${r1(c)} ms is over the ${b.render_max_ms} ms cap` : `render grew ${r1(d ?? 0)} ms (${b.render_pct}% allowed)`
+		};
+	});
+	row("CPU busy", "ms", cur.busy_ms, base?.busy_ms ?? null, (d) => ({
+		over: grew(d, base?.busy_ms ?? null, b.busy_pct, b.render_floor_ms),
+		limit: `+${b.busy_pct}%`,
+		why: `CPU busy grew ${r1(d ?? 0)} ms (${b.busy_pct}% allowed)`
+	}));
+	row("waiting on calls", "ms", cur.wait_ms, base?.wait_ms ?? null, () => ({
+		over: false,
+		limit: "informational"
+	}));
+	row("cold render extra", "ms", cur.cold_extra_ms, base?.cold_extra_ms ?? null, (d) => ({
+		over: d !== null && d > b.cold_extra_ms,
+		limit: `+${b.cold_extra_ms} ms`,
+		why: `the cold render's extra grew ${r1(d ?? 0)} ms (${b.cold_extra_ms} allowed)`
+	}));
+	row("page seed", "KB", cur.seed_kb, base?.seed_kb ?? null, (d, c) => ({
+		over: d !== null && d > b.seed_kb || c > b.seed_max_kb,
+		limit: `+${b.seed_kb} KB${Number.isFinite(b.seed_max_kb) ? `, max ${b.seed_max_kb} KB` : ""}`,
+		why: c > b.seed_max_kb ? `the seed is ${r1(c)} KB, over the ${b.seed_max_kb} KB cap` : `the seed grew ${r1(d ?? 0)} KB (${b.seed_kb} allowed)`
+	}));
+	row("island props", "KB", cur.props_kb, base?.props_kb ?? null, (d) => ({
+		over: d !== null && d > b.props_kb,
+		limit: `+${b.props_kb} KB`,
+		why: `island props grew ${r1(d ?? 0)} KB (${b.props_kb} allowed)`
+	}));
+	row("islands JS", "KB", cur.islands_js_kb, base?.islands_js_kb ?? null, (d, c) => ({
+		over: d !== null && d > b.islands_js_kb || c > b.islands_js_max_kb,
+		limit: `+${b.islands_js_kb} KB${Number.isFinite(b.islands_js_max_kb) ? `, max ${b.islands_js_max_kb} KB` : ""}`,
+		why: c > b.islands_js_max_kb ? `the islands load ${r1(c)} KB of JS, over the ${b.islands_js_max_kb} KB cap` : `the islands' JS grew ${r1(d ?? 0)} KB (${b.islands_js_kb} allowed)`
+	}));
+	row("islands", "n", cur.islands, base?.islands ?? null, () => ({
+		over: false,
+		limit: "informational"
+	}));
+	const movers = [];
+	if (base) {
+		const bc = new Map(base.components.map((c) => [c.name, c.self_ms]));
+		for (const c of cur.components) {
+			const bv = bc.get(c.name) ?? 0;
+			const delta = r1(c.self_ms - bv);
+			const over = bv > 0 && delta > 2 && delta > bv * b.component_pct / 100;
+			if (Math.abs(delta) >= .5) movers.push({
+				kind: "component",
+				name: c.name,
+				base: bv,
+				cur: c.self_ms,
+				delta,
+				over
+			});
+			if (over) failures.push(`${c.name} self time grew ${delta} ms (${b.component_pct}% allowed)`);
+		}
+		const bf = new Map(base.functions.map((f) => [f.name + "|" + f.file, f.self_ms]));
+		for (const f of cur.functions) {
+			const bv = bf.get(f.name + "|" + f.file) ?? 0;
+			const delta = r1(f.self_ms - bv);
+			if (Math.abs(delta) >= 1) movers.push({
+				kind: "function",
+				name: f.name,
+				file: f.file,
+				base: bv,
+				cur: f.self_ms,
+				delta,
+				over: false
+			});
+		}
+		const bp = new Map(base.paths.map((p) => [p.owner, p.ms]));
+		for (const p of cur.paths) {
+			const bv = bp.get(p.owner) ?? 0;
+			const delta = r1(p.ms - bv);
+			if (Math.abs(delta) >= 1) movers.push({
+				kind: "path",
+				name: p.owner,
+				base: bv,
+				cur: p.ms,
+				delta,
+				over: false
+			});
+		}
+		movers.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta));
+	}
+	const base_w = new Set(base?.warnings ?? []);
+	const cur_w = new Set(cur.warnings);
+	const added = [...cur_w].filter((w) => !base_w.has(w));
+	const gone = [...base_w].filter((w) => !cur_w.has(w));
+	for (const code of b.fail_on ?? []) if (added.includes(code) || !base && cur_w.has(code)) failures.push(`finding ${code} appeared`);
+	return {
+		page: cur.page,
+		fresh: !base,
+		rows,
+		movers: movers.slice(0, 12),
+		warnings: {
+			added,
+			gone
+		},
+		failures
+	};
+}
+export { DEFAULT_BUDGET, verdict };

package/dist/perf/measure.js

@@ -0,0 +1,102 @@
+// src/perf/measure.ts
+const r1 = (n) => Math.round(n * 10) / 10;
+const median = (xs) => xs.length ? [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)] : 0;
+/** One report → one page's snapshot. */
+function snapshot_page(page, report) {
+	const runs = (report.target?.runs ?? []).filter((n) => typeof n === "number");
+	const p50 = median(runs);
+	const cold = report.cold?.ms ?? 0;
+	const rows = report.ogygia?.island_rows ?? [];
+	const seen = /* @__PURE__ */ new Set();
+	let js = 0;
+	for (const r of rows) {
+		if (r.js_bytes == null) continue;
+		const mods = r.modules ?? [];
+		const fresh = mods.filter((m) => !seen.has(m));
+		if (!mods.length) js += r.js_bytes;
+		else js += r.js_bytes * fresh.length / mods.length;
+		for (const m of mods) seen.add(m);
+	}
+	const phases = {};
+	for (const ph of report.timeline?.phases ?? []) phases[ph.phase ?? ph.label ?? "other"] = r1((ph.cpu_ms ?? 0) + (ph.wait_ms ?? 0));
+	return {
+		page,
+		render_p50: r1(p50),
+		runs: runs.map(r1),
+		busy_ms: r1(report.summary?.busy_ms ?? 0),
+		wait_ms: r1(report.timeline?.wait_ms ?? 0),
+		cold_extra_ms: r1(cold && p50 ? Math.max(0, cold - p50) : 0),
+		seed_kb: r1((report.ogygia?.seed_bytes ?? 0) / 1024),
+		props_kb: r1((report.ogygia?.tail_bytes ?? 0) / 1024),
+		islands_js_kb: r1(js / 1024),
+		islands: report.ogygia?.islands ?? 0,
+		components: (report.components ?? []).slice().sort((a, b) => b.self_ms - a.self_ms).slice(0, 15).map((c) => ({
+			name: c.name,
+			self_ms: r1(c.self_ms),
+			total_ms: r1(c.total_ms)
+		})),
+		functions: (report.hot_functions ?? []).slice(0, 15).map((f) => ({
+			name: f.name,
+			file: f.file,
+			self_ms: r1(f.self_ms)
+		})),
+		paths: (report.paths ?? []).slice(0, 5).map((p) => ({
+			owner: p.owner.name,
+			ms: r1(p.ms),
+			fns: p.functions.length
+		})),
+		warnings: (report.findings ?? []).filter((f) => f.severity === "warn").map((f) => f.code),
+		phases
+	};
+}
+/** Render every page under the profiler and fold the reports into a snapshot. Pages are profiled
+*  one at a time (the server has one recorder); a page that fails throws with the reason. */
+async function measure(opts) {
+	const f = opts.fetch ?? globalThis.fetch;
+	const base = (opts.base ?? "/__profiler").replace(/\/$/, "");
+	const origin = opts.url.replace(/\/$/, "");
+	const runs = Math.max(1, Math.min(50, opts.runs ?? 5));
+	const pages = [];
+	let node = "";
+	for (const page of opts.pages) {
+		if (!page.startsWith("/")) throw new Error(`page must be a path on the site: ${page}`);
+		const url = `${origin}${base}/page?p=${encodeURIComponent(page)}&runs=${runs}&format=json`;
+		const ctrl = new AbortController();
+		const timer = setTimeout(() => ctrl.abort(), opts.timeout_ms ?? 12e4);
+		let res;
+		try {
+			res = await f(url, {
+				headers: {
+					accept: "application/json",
+					...opts.key ? { "x-profiler-key": opts.key } : {}
+				},
+				redirect: "follow",
+				signal: ctrl.signal
+			});
+		} catch (e) {
+			throw new Error(`${page}: the profiler did not answer (${e instanceof Error ? e.message : String(e)})`);
+		} finally {
+			clearTimeout(timer);
+		}
+		if (res.status === 409) throw new Error(`${page}: the profiler is busy on that server (another recording is running)`);
+		if (!res.ok) throw new Error(`${page}: the profiler answered ${res.status}${res.status === 401 || res.status === 302 || res.status === 303 ? " — is the key right (x-profiler-key)?" : ""}`);
+		let report;
+		try {
+			report = await res.json();
+		} catch {
+			throw new Error(`${page}: the profiler's answer was not JSON — is ${base} the profiler's path?`);
+		}
+		if (!node && report.node) node = report.node;
+		const snap = snapshot_page(page, report);
+		pages.push(snap);
+		opts.on_page?.(snap);
+	}
+	return {
+		version: 1,
+		at: Date.now(),
+		node,
+		...opts.label ? { label: opts.label } : {},
+		pages
+	};
+}
+export { measure, snapshot_page };

package/dist/perf/report.js

@@ -0,0 +1,55 @@
+// src/perf/report.ts
+const fmt = (n, unit) => n === null ? "—" : unit === "ms" ? `${n.toFixed(1)} ms` : unit === "KB" ? `${n.toFixed(1)} KB` : String(Math.round(n));
+const sign = (d, unit) => d === null ? "new" : `${d > 0 ? "+" : ""}${unit === "n" ? Math.round(d) : d.toFixed(1)}${unit === "ms" ? " ms" : unit === "KB" ? " KB" : ""}`;
+const pct = (p) => p === null ? "" : ` (${p > 0 ? "+" : ""}${p.toFixed(0)}%)`;
+function markdown(v, opts = {}) {
+	const lines = [];
+	lines.push(`### ${opts.title ?? "Performance"}: ${v.ok ? "✅ within budget" : `❌ ${v.failures.length} budget failure${v.failures.length === 1 ? "" : "s"}`}`);
+	lines.push("");
+	if (!v.ok) {
+		for (const f of v.failures) lines.push(`- ❌ ${f}`);
+		lines.push("");
+	}
+	for (const p of v.pages) lines.push(...page_md(p, opts.links?.[p.page]));
+	if (v.missing.length) lines.push(`_Not measured this run (in the baseline): ${v.missing.join(", ")}_`, "");
+	lines.push("<sub>ogygia profiler · medians over the runs · a positive Δ is slower or bigger</sub>");
+	return lines.join("\n");
+}
+function page_md(p, links) {
+	const out = [];
+	const head = p.fresh ? `${p.page} (new page, no baseline)` : p.page;
+	const link = links?.cur ? ` · [report](${links.cur})${links.base ? ` · [baseline](${links.base})` : ""}` : "";
+	out.push(`#### ${p.failures.length ? "❌" : "✅"} \`${head}\`${link}`);
+	out.push("");
+	out.push("| metric | base | PR | Δ | budget |");
+	out.push("|---|---:|---:|---:|---|");
+	for (const r of p.rows) {
+		const flag = r.over ? " ❌" : "";
+		out.push(`| ${r.metric} | ${fmt(r.base, r.unit)} | ${fmt(r.cur, r.unit)} | ${sign(r.delta, r.unit)}${pct(r.pct)}${flag} | ${r.limit} |`);
+	}
+	out.push("");
+	const movers = p.movers.slice(0, 3);
+	if (movers.length) {
+		out.push("**Biggest movers**");
+		for (const m of movers) out.push(`- ${m.over ? "❌ " : ""}${m.kind} \`${m.name}\`${m.file ? ` (${m.file})` : ""}: ${m.base.toFixed(1)} → ${m.cur.toFixed(1)} ms (${m.delta > 0 ? "+" : ""}${m.delta.toFixed(1)})`);
+		out.push("");
+	}
+	if (p.warnings.added.length || p.warnings.gone.length) {
+		if (p.warnings.added.length) out.push(`**Findings that appeared:** ${p.warnings.added.map((w) => `\`${w}\``).join(", ")}`);
+		if (p.warnings.gone.length) out.push(`**Findings that went away:** ${p.warnings.gone.map((w) => `\`${w}\``).join(", ")}`);
+		out.push("");
+	}
+	return out;
+}
+/** The terminal's view: one line per page, the failures spelled out. */
+function summary(v) {
+	const lines = [];
+	for (const p of v.pages) {
+		const render = p.rows.find((r) => r.metric === "render (median)");
+		lines.push(`${p.failures.length ? "✗" : "✓"} ${p.page}  render ${fmt(render.cur, "ms")}${render.delta !== null ? ` (${sign(render.delta, "ms")}${pct(render.pct)})` : " (new)"}${p.failures.length ? `\n    ${p.failures.join("\n    ")}` : ""}`);
+	}
+	if (v.missing.length) lines.push(`  not measured: ${v.missing.join(", ")}`);
+	lines.push(v.ok ? "within budget" : `${v.failures.length} budget failure${v.failures.length === 1 ? "" : "s"}`);
+	return lines.join("\n");
+}
+export { markdown, summary };

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@ogygia/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.11.0",
+  "description": "The ogygia command line: init and site scaffolds, the AI skill, the MCP server, perf budgets and bisect, federation keys and catalogs",
+  "keywords": [
+    "cli",
+    "mcp",
+    "ogygia",
+    "sveltekit"
+  ],
+  "homepage": "https://ogygiajs.dev",
+  "license": "MIT",
+  "author": "Puru Vijayvargia <devpuruvj@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ogygiajs/ogygia.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "ogygia-cli": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "ai",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./bin": "./dist/cli.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@sveltejs/sv-utils": "^0.3.3",
+    "@types/node": "^26.1.2",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "svelte": "5.56.8",
+    "tsdown": "^0.23.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.12",
+    "@ogygia/core": "0.11.0",
+    "@ogygia/devtools": "0.11.0",
+    "@ogygia/tooling": "0.0.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.62.0",
+    "svelte": "^5.56.8",
+    "@ogygia/core": "^0.11.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc -p . && tsc -p test && vitest run",
+    "test": "vitest run"
+  }
 }