@ogygia/devtools 0.0.0-stage → 0.11.0

package/dist/profiler/storage/index.js

@@ -0,0 +1,76 @@
+// src/profiler/storage/index.ts
+/** An in-memory store — a Map with an LRU cap. The profiler without a store keeps reports in its own
+*  memory already, so this adds nothing there; it is for tests and a model for a custom store.
+*  Nothing survives a restart. */
+function memoryStore(cap = 50) {
+	const reports = /* @__PURE__ */ new Map();
+	const visits = [];
+	return {
+		kind: "memory",
+		putReport(rec) {
+			reports.delete(rec.id);
+			reports.set(rec.id, rec);
+			while (reports.size > cap) {
+				const oldest = reports.keys().next().value;
+				if (oldest === void 0) break;
+				reports.delete(oldest);
+			}
+		},
+		getReport(id) {
+			return reports.get(id)?.dump ?? null;
+		},
+		listReports(limit = 30) {
+			return [...reports.values()].sort((a, b) => b.created - a.created).slice(0, limit).map(({ dump: _dump, ...s }) => s);
+		},
+		deleteReport(id) {
+			reports.delete(id);
+		},
+		prune(keep) {
+			while (reports.size > keep) {
+				const oldest = reports.keys().next().value;
+				if (oldest === void 0) break;
+				reports.delete(oldest);
+			}
+		},
+		putVisit(rec) {
+			visits.push(rec);
+			if (visits.length > 2e3) visits.shift();
+		},
+		listVisits(page, limit = 10) {
+			return visits.filter((v) => v.page === page).sort((a, b) => b.at - a.at).slice(0, limit);
+		}
+	};
+}
+/** Pull the summary columns off a record for storing them alongside the dump. */
+function recordColumns(rec) {
+	return {
+		id: rec.id,
+		created: rec.created,
+		page: rec.page,
+		trigger: rec.trigger,
+		label: rec.label,
+		median: rec.median
+	};
+}
+/**
+* Give the profiler its store AT RUNTIME. The profiler is configured in `vite.config.ts` (build
+* time, serializable), but a store is a live object with a DB connection — so it is set here
+* instead, once, before the first request:
+*
+*   // src/hooks.server.ts
+*   import { setProfilerStore } from '@ogygia/devtools/profiler/storage';
+*   import { postgresStore } from '@ogygia/devtools/profiler/storage/postgres';
+*   setProfilerStore(postgresStore(process.env.DATABASE_URL!));
+*
+* The profiler reads this when it mounts and every finished report is written there. Call it before
+* the profiler handles its first request; a later call is ignored (the instance already mounted).
+*/
+const STORE_SLOT = Symbol.for("ogygia.profiler.store.v1");
+function setProfilerStore(store) {
+	globalThis[STORE_SLOT] = store;
+}
+/** The store set by {@link setProfilerStore}, if any — read by the profiler host on mount. */
+function getProfilerStore() {
+	return globalThis[STORE_SLOT];
+}
+export { getProfilerStore, memoryStore, recordColumns, setProfilerStore };

package/dist/profiler/storage/postgres.d.ts

@@ -0,0 +1,12 @@
+import { ProfilerStore } from "./index.js";
+interface PgLike {
+  query(text: string, params?: unknown[]): Promise<{
+    rows: Record<string, unknown>[];
+  }>;
+  end?(): Promise<void>;
+}
+export declare function postgresStore(client: PgLike | string, opts?: {
+  schema?: string;
+  table?: string;
+}): ProfilerStore;
+export {};

package/dist/profiler/storage/postgres.js

@@ -0,0 +1,94 @@
+import { MAX_VISITS_PER_KEY } from "./visits.js";
+// src/profiler/storage/postgres.ts
+async function resolve(client) {
+	if (typeof client !== "string") return client;
+	const pg = await import("pg");
+	const Pool = pg.Pool ?? pg.default?.Pool;
+	if (!Pool) throw new Error("ogygia/profiler: postgresStore needs the 'pg' package.");
+	return new Pool({ connectionString: client });
+}
+function postgresStore(client, opts = {}) {
+	const base = opts.table ?? "ogygia";
+	const q = (n) => opts.schema ? `"${opts.schema}"."${base}_${n}"` : `"${base}_${n}"`;
+	const R = q("reports");
+	const V = q("visits");
+	let c = null;
+	let ready = null;
+	const need = async () => {
+		c ??= await resolve(client);
+		ready ??= (async () => {
+			if (opts.schema) await c.query(`CREATE SCHEMA IF NOT EXISTS "${opts.schema}"`);
+			await c.query(`CREATE TABLE IF NOT EXISTS ${R} (id TEXT PRIMARY KEY, created BIGINT NOT NULL, page TEXT, trigger TEXT, label TEXT, median DOUBLE PRECISION, dump JSONB NOT NULL)`);
+			await c.query(`CREATE INDEX IF NOT EXISTS ${base}_reports_created ON ${R} (created DESC)`);
+			await c.query(`CREATE TABLE IF NOT EXISTS ${V} (key TEXT PRIMARY KEY, page TEXT NOT NULL, at BIGINT NOT NULL, visit JSONB NOT NULL)`);
+			await c.query(`CREATE INDEX IF NOT EXISTS ${base}_visits_page ON ${V} (page, at DESC)`);
+		})();
+		await ready;
+		return c;
+	};
+	return {
+		kind: "postgres",
+		async init() {
+			await need();
+		},
+		async putReport(rec) {
+			await (await need()).query(`INSERT INTO ${R} (id,created,page,trigger,label,median,dump) VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb)
+				 ON CONFLICT (id) DO UPDATE SET created=EXCLUDED.created,page=EXCLUDED.page,trigger=EXCLUDED.trigger,label=EXCLUDED.label,median=EXCLUDED.median,dump=EXCLUDED.dump`, [
+				rec.id,
+				rec.created,
+				rec.page,
+				rec.trigger,
+				rec.label,
+				rec.median,
+				rec.dump
+			]);
+		},
+		async getReport(id) {
+			const { rows } = await (await need()).query(`SELECT dump FROM ${R} WHERE id = $1`, [id]);
+			if (!rows.length) return null;
+			const d = rows[0].dump;
+			return typeof d === "string" ? d : JSON.stringify(d);
+		},
+		async listReports(limit = 30) {
+			const { rows } = await (await need()).query(`SELECT id,created,page,trigger,label,median FROM ${R} ORDER BY created DESC LIMIT $1`, [limit]);
+			return rows.map((r) => ({
+				id: r.id,
+				created: Number(r.created),
+				page: r.page ?? null,
+				trigger: r.trigger,
+				label: r.label,
+				median: r.median === null ? null : Number(r.median)
+			}));
+		},
+		async deleteReport(id) {
+			await (await need()).query(`DELETE FROM ${R} WHERE id = $1`, [id]);
+		},
+		async prune(keep) {
+			await (await need()).query(`DELETE FROM ${R} WHERE id NOT IN (SELECT id FROM ${R} ORDER BY created DESC LIMIT $1)`, [keep]);
+		},
+		async putVisit(rec) {
+			const db = await need();
+			await db.query(`INSERT INTO ${V} (key,page,at,visit) VALUES ($1,$2,$3,$4::jsonb) ON CONFLICT (key) DO UPDATE SET at=EXCLUDED.at,visit=EXCLUDED.visit`, [
+				rec.key,
+				rec.page,
+				rec.at,
+				rec.visit
+			]);
+			await db.query(`DELETE FROM ${V} WHERE page = $1 AND key NOT IN (SELECT key FROM ${V} WHERE page = $1 ORDER BY at DESC LIMIT $2)`, [rec.page, MAX_VISITS_PER_KEY]);
+		},
+		async listVisits(page, limit = 10) {
+			const { rows } = await (await need()).query(`SELECT key,page,at,visit FROM ${V} WHERE page = $1 ORDER BY at DESC LIMIT $2`, [page, limit]);
+			return rows.map((r) => ({
+				key: r.key,
+				page: r.page,
+				at: Number(r.at),
+				visit: typeof r.visit === "string" ? r.visit : JSON.stringify(r.visit)
+			}));
+		},
+		async close() {
+			await c?.end?.();
+			c = null;
+		}
+	};
+}
+export { postgresStore };

package/dist/profiler/storage/redis.d.ts

@@ -0,0 +1,19 @@
+import { ProfilerStore } from "./index.js";
+/** The subset of a Redis client this store uses — node-redis and ioredis both satisfy it (their
+ *  method names differ in case, and a few calls take options objects on one and arguments on the
+ *  other; the flavour is read once, below). */
+interface RedisLike {
+  set(key: string, val: string, ...rest: unknown[]): Promise<unknown>;
+  get(key: string): Promise<string | null>;
+  del(key: string | string[]): Promise<unknown>;
+  zadd?(key: string, ...rest: unknown[]): Promise<unknown>;
+  zrem?(key: string, ...members: string[]): Promise<unknown>;
+  zrange?(key: string, start: number, stop: number, ...rest: unknown[]): Promise<string[]>;
+  zcard?(key: string): Promise<number>;
+  connect?(): Promise<void>;
+}
+export declare function redisStore(client: RedisLike | string, opts?: {
+  ttlSeconds?: number;
+  prefix?: string;
+}): ProfilerStore;
+export {};

package/dist/profiler/storage/redis.js

@@ -0,0 +1,148 @@
+import { MAX_VISITS_PER_KEY } from "./visits.js";
+// src/profiler/storage/redis.ts
+/** reports kept at most, whatever the host prunes to (a store used on its own still has a cap) */
+const MAX_REPORTS = 1e3;
+async function resolve(client) {
+	if (typeof client !== "string") return client;
+	const nodeRedis = "redis";
+	const ioRedis = "ioredis";
+	try {
+		const { createClient } = await import(nodeRedis);
+		const c = createClient({ url: client });
+		await c.connect?.();
+		return c;
+	} catch {}
+	return new (await (import(ioRedis))).default(client);
+}
+function redisStore(client, opts = {}) {
+	const ttl = opts.ttlSeconds;
+	const prefix = opts.prefix ?? "og:";
+	const R = `${prefix}report:`;
+	const RZ = `${prefix}reports`;
+	const V = `${prefix}visit:`;
+	const VZ = (page) => `${V}z:${page}`;
+	let c = null;
+	const need = async () => c ??= await resolve(client);
+	const node = (r) => typeof r.zAdd === "function" ? r : null;
+	const setStr = async (r, key, val) => {
+		const n = node(r);
+		if (!ttl) await r.set(key, val);
+		else if (n) await n.set(key, val, { EX: ttl });
+		else await r.set(key, val, "EX", ttl);
+	};
+	const zadd = (r, key, score, member) => {
+		const n = node(r);
+		return n ? n.zAdd(key, {
+			score,
+			value: member
+		}) : r.zadd(key, score, member);
+	};
+	const zrem = (r, key, members) => {
+		if (!members.length) return Promise.resolve();
+		const n = node(r);
+		return n ? n.zRem(key, members) : r.zrem(key, ...members);
+	};
+	const zrange = (r, key, a, b, rev = false) => {
+		const n = node(r);
+		if (n) return rev ? n.zRange(key, a, b, { REV: true }) : n.zRange(key, a, b);
+		return rev ? r.zrange(key, a, b, "REV") : r.zrange(key, a, b);
+	};
+	const zcard = (r, key) => {
+		const n = node(r);
+		return n ? n.zCard(key) : r.zcard(key);
+	};
+	/** drop every member but the newest `keep`, with the keys they name */
+	const trim = async (r, key, item, keep) => {
+		const stale = await zrange(r, key, 0, -(keep + 1));
+		if (!stale.length) return;
+		await r.del(stale.map((m) => item + m));
+		await zrem(r, key, stale);
+	};
+	return {
+		kind: "redis",
+		async init() {
+			await need();
+		},
+		async putReport(rec) {
+			const r = await need();
+			const summary = {
+				id: rec.id,
+				created: rec.created,
+				page: rec.page,
+				trigger: rec.trigger,
+				label: rec.label,
+				median: rec.median
+			};
+			await setStr(r, R + rec.id, JSON.stringify({
+				summary,
+				dump: rec.dump
+			}));
+			await zadd(r, RZ, rec.created, rec.id);
+			if (await zcard(r, RZ) > MAX_REPORTS) await trim(r, RZ, R, MAX_REPORTS);
+		},
+		async getReport(id) {
+			const raw = await (await need()).get(R + id);
+			if (!raw) return null;
+			try {
+				return JSON.parse(raw).dump;
+			} catch {
+				return null;
+			}
+		},
+		async listReports(limit = 30) {
+			const r = await need();
+			const ids = await zrange(r, RZ, 0, limit - 1, true);
+			const out = [];
+			const gone = [];
+			for (const id of ids) {
+				const raw = await r.get(R + id);
+				if (!raw) {
+					gone.push(id);
+					continue;
+				}
+				try {
+					out.push(JSON.parse(raw).summary);
+				} catch {}
+			}
+			await zrem(r, RZ, gone);
+			return out;
+		},
+		async deleteReport(id) {
+			const r = await need();
+			await r.del(R + id);
+			await zrem(r, RZ, [id]);
+		},
+		async prune(keep) {
+			await trim(await need(), RZ, R, keep);
+		},
+		async putVisit(rec) {
+			const r = await need();
+			await setStr(r, V + rec.key, JSON.stringify(rec));
+			await zadd(r, VZ(rec.page), rec.at, rec.key);
+			if (await zcard(r, VZ(rec.page)) > 2e3) await trim(r, VZ(rec.page), V, MAX_VISITS_PER_KEY);
+		},
+		async listVisits(page, limit = 10) {
+			const r = await need();
+			const keys = await zrange(r, VZ(page), 0, limit - 1, true);
+			const out = [];
+			const gone = [];
+			for (const k of keys) {
+				const raw = await r.get(V + k);
+				if (!raw) {
+					gone.push(k);
+					continue;
+				}
+				try {
+					out.push(JSON.parse(raw));
+				} catch {}
+			}
+			await zrem(r, VZ(page), gone);
+			return out;
+		},
+		async close() {
+			await c?.quit?.().catch(() => {});
+			c = null;
+		}
+	};
+}
+export { redisStore };

package/dist/profiler/storage/sqlite.d.ts

@@ -0,0 +1,2 @@
+import { ProfilerStore } from "./index.js";
+export declare function sqliteStore(filename?: string): ProfilerStore;

package/dist/profiler/storage/sqlite.js

@@ -0,0 +1,85 @@
+import { MAX_VISITS_PER_KEY } from "./visits.js";
+import { createRequire } from "node:module";
+// src/profiler/storage/sqlite.ts
+/**
+* SQLite report store — a file (or `:memory:`). The simplest durable backend: one file, no server,
+* survives a restart. Uses Node's built-in `node:sqlite` (Node 22.5+) when present, else
+* `better-sqlite3` if installed. Both are synchronous, which is fine here: a put is one small
+* insert, a get one indexed lookup, off the request's hot path (a report is written once, after
+* the recording).
+*
+*   // src/hooks.server.ts
+*   import { setProfilerStore } from '@ogygia/devtools/profiler/storage';
+*   import { sqliteStore } from '@ogygia/devtools/profiler/storage/sqlite';
+*   setProfilerStore(sqliteStore('.ogygia/profiles.db'));
+*/
+const require = createRequire(import.meta.url);
+/** Open a synchronous sqlite database from whichever driver is installed. */
+function open(filename) {
+	if (filename !== ":memory:" && !filename.startsWith("file::memory:")) try {
+		const fs = require("node:fs");
+		const dir = require("node:path").dirname(filename);
+		if (dir && dir !== ".") fs.mkdirSync(dir, { recursive: true });
+	} catch {}
+	try {
+		const { DatabaseSync } = require("node:sqlite");
+		return new DatabaseSync(filename);
+	} catch {}
+	try {
+		return new (require("better-sqlite3"))(filename);
+	} catch {
+		throw new Error("ogygia/profiler: sqliteStore needs Node 22.5+ (built-in node:sqlite) or the 'better-sqlite3' package.");
+	}
+}
+function sqliteStore(filename = ".ogygia/profiles.db") {
+	let db = null;
+	const need = () => {
+		if (db) return db;
+		db = open(filename);
+		db.exec(`
+			CREATE TABLE IF NOT EXISTS reports (
+				id TEXT PRIMARY KEY, created INTEGER NOT NULL, page TEXT, trigger TEXT,
+				label TEXT, median REAL, dump TEXT NOT NULL
+			);
+			CREATE INDEX IF NOT EXISTS reports_created ON reports (created);
+			CREATE TABLE IF NOT EXISTS visits (
+				key TEXT PRIMARY KEY, page TEXT NOT NULL, at INTEGER NOT NULL, visit TEXT NOT NULL
+			);
+			CREATE INDEX IF NOT EXISTS visits_page ON visits (page, at);
+		`);
+		return db;
+	};
+	return {
+		kind: "sqlite",
+		init() {
+			need();
+		},
+		putReport(rec) {
+			need().prepare("INSERT INTO reports (id,created,page,trigger,label,median,dump) VALUES (?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET created=excluded.created,page=excluded.page,trigger=excluded.trigger,label=excluded.label,median=excluded.median,dump=excluded.dump").run(rec.id, rec.created, rec.page, rec.trigger, rec.label, rec.median, rec.dump);
+		},
+		getReport(id) {
+			return need().prepare("SELECT dump FROM reports WHERE id = ?").get(id)?.dump ?? null;
+		},
+		listReports(limit = 30) {
+			return need().prepare("SELECT id,created,page,trigger,label,median FROM reports ORDER BY created DESC LIMIT ?").all(limit);
+		},
+		deleteReport(id) {
+			need().prepare("DELETE FROM reports WHERE id = ?").run(id);
+		},
+		prune(keep) {
+			need().prepare("DELETE FROM reports WHERE id NOT IN (SELECT id FROM reports ORDER BY created DESC LIMIT ?)").run(keep);
+		},
+		putVisit(rec) {
+			need().prepare("INSERT INTO visits (key,page,at,visit) VALUES (?,?,?,?) ON CONFLICT(key) DO UPDATE SET at=excluded.at,visit=excluded.visit").run(rec.key, rec.page, rec.at, rec.visit);
+			need().prepare("DELETE FROM visits WHERE page = ? AND key NOT IN (SELECT key FROM visits WHERE page = ? ORDER BY at DESC LIMIT ?)").run(rec.page, rec.page, MAX_VISITS_PER_KEY);
+		},
+		listVisits(page, limit = 10) {
+			return need().prepare("SELECT key,page,at,visit FROM visits WHERE page = ? ORDER BY at DESC LIMIT ?").all(page, limit);
+		},
+		close() {
+			db?.close();
+			db = null;
+		}
+	};
+}
+export { sqliteStore };

package/dist/profiler/storage/visits.d.ts

@@ -0,0 +1,4 @@
+/** The most visit rows a bundled store keeps under one `page` key, newest first. A server window
+ *  writes every request it saw (from any instance) under ONE key and reads up to this many back,
+ *  so the store's retention and the window's read are the same number. */
+export declare const MAX_VISITS_PER_KEY = 2e3;

package/dist/profiler/storage/visits.js

@@ -0,0 +1,6 @@
+// src/profiler/storage/visits.ts
+/** The most visit rows a bundled store keeps under one `page` key, newest first. A server window
+*  writes every request it saw (from any instance) under ONE key and reads up to this many back,
+*  so the store's retention and the window's read are the same number. */
+const MAX_VISITS_PER_KEY = 2e3;
+export { MAX_VISITS_PER_KEY };

package/dist/profiler/stream-tail.d.ts

@@ -0,0 +1,26 @@
+import { ByteStrip, StripKind } from "./byte-strip.js";
+export interface StreamTail {
+  /** the early part: its last byte left the server at `early_ms` (ms into the render) */
+  early_ms: number;
+  early_bytes: number;
+  /** the tail: its last byte left at `late_ms` */
+  late_ms: number;
+  late_bytes: number;
+  /** each streamed promise that settled in the tail, in the order it left: its `page.data` key
+   *  (a dotted path one level deep; null when the seed cannot say) and when */
+  keys: {
+    key: string | null;
+    id: number;
+    left_ms: number;
+  }[];
+  /** the tail's other bytes by what they are (an island's markup: its fingerprint) */
+  other: {
+    kind: StripKind;
+    label?: string;
+    bytes: number;
+  }[];
+}
+export declare function stream_tail(html: string, strip: ByteStrip, chunks: {
+  end: number;
+  t: number;
+}[]): StreamTail | null;

package/dist/profiler/stream-tail.js

@@ -0,0 +1,74 @@
+import { left_at } from "./byte-strip.js";
+import { defer_keys } from "@ogygia/core/insights";
+import { PAGE_DEFER_GLOBAL, PAGE_DEFER_KEY } from "@ogygia/core/internal/instruments";
+// src/profiler/stream-tail.ts
+/**
+* WHAT HELD THE DOCUMENT OPEN — a streamed page ships its shell, then keeps the response open until
+* its last streamed promise settles (a `<script>__ogygia_page_resolve(id, …)<\/script>` per settle,
+* after `</html>`). The browser fires DOMContentLoaded only when the document ends, and islands wake
+* after it, so the slowest streamed promise holds every island on the page. Read off the profiled
+* render's body: the biggest pause between chunks splits the early part from the late tail, and each
+* resolve script in the tail is named by the `page.data` key its id stands for (page-insights
+* `defer_keys`, the Page tab's own reading). Pure; indexOf only.
+*/
+/** a pause between chunks shorter than this is the server writing, not waiting */
+const MIN_PAUSE_MS = 100;
+function stream_tail(html, strip, chunks) {
+	if (chunks.length < 2) return null;
+	let split = -1;
+	let pause = 0;
+	for (let i = 1; i < chunks.length; i++) {
+		const d = chunks[i].t - chunks[i - 1].t;
+		if (d > pause) {
+			pause = d;
+			split = i;
+		}
+	}
+	if (split === -1 || pause < MIN_PAUSE_MS) return null;
+	const early_end = chunks[split - 1].end;
+	const last = chunks[chunks.length - 1];
+	const names = defer_keys(html, PAGE_DEFER_KEY);
+	const keys = [];
+	const call = `${PAGE_DEFER_GLOBAL}(`;
+	const resolves = [];
+	for (let at = html.indexOf(call, early_end); at !== -1; at = html.indexOf(call, at + call.length)) {
+		let n = 0;
+		let j = at + call.length;
+		let digits = 0;
+		for (; j < html.length && html.charCodeAt(j) >= 48 && html.charCodeAt(j) <= 57; j++, digits++) n = n * 10 + (html.charCodeAt(j) - 48);
+		if (!digits) continue;
+		keys.push({
+			key: names.get(n) ?? null,
+			id: n,
+			left_ms: left_at(at, chunks) ?? last.t
+		});
+		resolves.push({
+			start: at,
+			end: html.indexOf("<\/script", at)
+		});
+	}
+	const in_resolve = (s) => resolves.some((r) => s.start <= r.start && r.end <= s.end);
+	const other = /* @__PURE__ */ new Map();
+	for (const s of strip.segments) {
+		const from = Math.max(s.start, early_end);
+		if (s.end <= from || in_resolve(s)) continue;
+		const k = `${s.kind}|${s.label ?? ""}`;
+		const o = other.get(k) ?? {
+			kind: s.kind,
+			...s.label ? { label: s.label } : {},
+			bytes: 0
+		};
+		o.bytes += s.end - from;
+		other.set(k, o);
+	}
+	keys.sort((a, b) => a.left_ms - b.left_ms);
+	return {
+		early_ms: chunks[split - 1].t,
+		early_bytes: early_end,
+		late_ms: last.t,
+		late_bytes: html.length - early_end,
+		keys,
+		other: [...other.values()].sort((a, b) => b.bytes - a.bytes)
+	};
+}
+export { stream_tail };