@ogygia/devtools 0.0.0 → 0.11.0

package/dist/profiler/profiler-router.d.ts

@@ -0,0 +1,245 @@
+import { SiteFix } from "./site-fixes.js";
+import { HoleSlots } from "./hole-slots.js";
+import { Comparison, Since } from "./compare.js";
+import { Analysis } from "./analyze.js";
+import { ReportExtras, ReportMeta, RequestEntry, RouteAgg } from "./report.js";
+import { SampledSummary, StoredReport, TrapStatus } from "./index.js";
+import { SinkRow } from "./sink.js";
+import { Ctx, PageDef, Router } from "@ogygia/router";
+/** One page's profile history: every page-mode report of it, oldest first, by median run. */
+export interface PageHistory {
+  page: string;
+  points: {
+    id: string;
+    created: number;
+    median: number;
+    score?: number;
+  }[];
+}
+/** What the router calls into the host for. Return types here ARE the components' `data` types. */
+export interface ProfilerDeps {
+  base: string;
+  /** Table-wide guard: a deny Response short-circuits every route (v2 load-returns-Response), else
+   *  `undefined` = allow. The load below turns allow into the seeded `{ base }`. */
+  auth_guard(c: Ctx): Promise<Response | undefined>;
+  /** The runtime's hydration beacon (POST, authed): browser-side island timings, joined by fingerprint. */
+  beacon(c: Ctx): Promise<Response>;
+  /** A recording window you start and stop (POST, authed): the server's CPU, calls and requests
+   *  while a test (or the devtools Record tab) drives the app; stop answers the report's JSON. */
+  window_start(c: Ctx): Promise<Response>;
+  window_stop(c: Ctx): Promise<Response>;
+  /** Is this request logged in? The public bare report page gates its SERVER data on this (a share
+   *  `#fragment` renders without it). */
+  authed(c: Ctx): Promise<boolean>;
+  dashboard(c: Ctx): {
+    base: string;
+    recent: RequestEntry[];
+    routes: RouteAgg[];
+    /** the request tag the slowest-routes table is split by (`?by=tenant`), when any */
+    by: string | null;
+    /** every tag key seen in the log (`tag()`), for the split-by control */
+    tag_keys: string[];
+    reports: ReportMeta[];
+    /** report id → its biggest slow pattern (what to fix first) and how many more it found */
+    top_fix: Record<string, {
+      title: string;
+      save_ms: number;
+      wait: boolean;
+      more: number;
+    }>;
+    /** the lines that slow two or more profiled pages, what fixing each gives back per page and in all */
+    site_fixes: SiteFix[];
+    /** the holes the server rendered: render, cache, and who held the render slots others waited for */
+    holes: HoleSlots | null;
+    recording: boolean;
+    dev: boolean;
+    rss_mb: number;
+    inflight: number;
+    /** page-mode reports grouped by page (the history sparklines + compare pairs) */
+    history: PageHistory[];
+    /** the trap (catch the slow one), when configured */
+    trap: TrapStatus | null;
+    /** the always-on sampler's rolling hot-functions table, when configured */
+    sampled: SampledSummary | null;
+    /** why the background recorders are off (a serverless host), when they are */
+    background_note: string | null;
+  };
+  /** Two stored reports side by side (404 when either expired). */
+  /** `cmp` is null when this server no longer holds one of the reports: the page then compares
+   *  from the browser's store (the ids come back so it can) */
+  compare(a: string | undefined, b: string | undefined): {
+    base: string;
+    cmp: Comparison | null;
+    a: string;
+    b: string;
+  };
+  /** the whole-site pictures: this instance's rows, the sink's status, a URL the browser reads rows from */
+  site(c: Ctx): {
+    base: string;
+    rows: SinkRow[];
+    sink: {
+      url: string;
+      last: {
+        at: number;
+        ok: boolean;
+        rows: number;
+        error?: string;
+      } | null;
+      buffered: number;
+    } | null;
+    from: string | null;
+    ephemeral: boolean;
+  };
+  /** A caught request profiled again in full page mode with the inputs it was caught with. */
+  replay(id: string | undefined, c: Ctx): Promise<Response>;
+  /** DEV ONLY: a few lines of a local source file around a line (the row's source peek). */
+  source(c: Ctx): Promise<Response>;
+  run_page(c: Ctx): Response | {
+    base: string;
+    path: string;
+    runs: number;
+    format: string;
+    against?: string;
+  };
+  record_page(c: Ctx): Promise<Response>;
+  reset(c: Ctx): Response;
+  /** A tiny live-status poll for the sidebar (and, later, a hosted dashboard): is a recording
+   *  running right now, how many requests are in flight, the instance's memory, how many reports
+   *  this instance holds. Cheap and side-effect-free. */
+  status(c: Ctx): {
+    recording: boolean;
+    inflight: number;
+    rss_mb: number;
+    reports: number;
+  };
+  /** `session_problem`: why a login that just succeeded still has no session (null otherwise). */
+  login_props(c: Ctx): {
+    base: string;
+    next: string;
+    session_problem: string | null;
+  };
+  login(c: Ctx): Promise<Response>;
+  logout(c: Ctx): Response;
+  upload(c: Ctx): Promise<Response>;
+  report_stored(id: string | undefined): StoredReport | undefined;
+  /** Like `report_stored`, but falls through to the configured storage backend (SQLite/Redis/
+   *  Postgres) on a memory miss and reconstructs the report from its stored dump — so a report
+   *  survives the instance that made it. Memory-only when no store is configured. */
+  report_load(id: string | undefined): Promise<StoredReport | undefined>;
+  /** The reports the backend holds (summaries), for the sidebar's shared list. Empty with no store. */
+  list_stored(limit?: number): Promise<{
+    id: string;
+    label: string;
+    page?: string;
+    created: number;
+  }[]>;
+  /** The login page for THIS url (`?next=` back here) when the UI is secret-gated; null when a
+   *  login makes no sense (dev is open; no secret = no UI). */
+  login_url(c: Ctx): string | null;
+  report_view(stored: StoredReport): Promise<{
+    a: Analysis;
+    meta: ReportMeta;
+    base: string;
+    extras: ReportExtras;
+    ogpB64?: string;
+    /** this page's other page-mode reports (page mode only) and the one just before this */
+    history: PageHistory | null;
+    prev: string | null;
+    /** against the previous profile of this page, when this server still holds it */
+    since: Since | null;
+    /** recorded on a dev server — the source peek is available */
+    dev: boolean;
+  }>;
+  report_json(stored: StoredReport): Response | Promise<Response>;
+  report_dump_json(stored: StoredReport): Response;
+  /** ONE self-contained HTML file of the report (styles, runtime and island chunks inlined) —
+   *  opens from disk with the islands live. A built app only; dev answers 400. */
+  report_html(stored: StoredReport, c: Ctx): Promise<Response>;
+  /** A report's standalone file, agent JSON or plain dump, built from the report the request
+   *  carries (the page's .ogp bytes or the browser's kept copy): works on any instance. */
+  report_posted(c: Ctx, as: "html" | "json" | "dump" | "ogp"): Promise<Response>;
+  report_raw(stored: StoredReport): Promise<Response>;
+}
+type CtxFn<R> = (c: Ctx) => R;
+type ProfilerPage<Load, Actions = unknown> = PageDef<readonly [], Load, Actions, unknown, unknown>;
+/** Build the profiler router. Auth is the table-wide `load` (a redirect/deny short-circuits every
+ *  route; on allow it seeds `{ base }`); thrown `error()` renders the root `Message` boundary.
+ *  `/report/[id]` is PUBLIC (a share `#fragment` decrypts client-side); its `.json`/`.dump`/`/raw`
+ *  siblings keep the suffix so they stay behind the guard's server-data gate. Endpoints are
+ *  the plain `{ GET }` object form (bare handlers; `c.params.id` reads from the table key). */
+export declare function build_profiler_router(d: ProfilerDeps): Router<{
+  readonly "/": ProfilerPage<(c: Ctx) => ReturnType<ProfilerDeps["dashboard"]>>;
+  readonly "/run": ProfilerPage<(c: Ctx) => ReturnType<ProfilerDeps["run_page"]>>;
+  readonly "/page": {
+    readonly GET: CtxFn<Promise<Response>>;
+  };
+  readonly "/reset": {
+    readonly GET: CtxFn<Response>;
+  };
+  readonly "/status.json": {
+    readonly GET: CtxFn<Response>;
+  };
+  readonly "/beacon": {
+    readonly POST: CtxFn<Promise<Response>>;
+  };
+  readonly "/window/start": {
+    readonly POST: CtxFn<Promise<Response>>;
+  };
+  readonly "/window/stop": {
+    readonly POST: CtxFn<Promise<Response>>;
+  };
+  readonly "/login": ProfilerPage<(c: Ctx) => ReturnType<ProfilerDeps["login_props"]>, {
+    default: CtxFn<Promise<Response>>;
+  }>;
+  readonly "/logout": {
+    readonly GET: CtxFn<Response>;
+  };
+  readonly "/view": ProfilerPage<() => {
+    base: string;
+  }, {
+    default: CtxFn<Promise<Response>>;
+  }>;
+  readonly "/reports.json": {
+    readonly GET: CtxFn<Promise<Response>>;
+  };
+  readonly "/report/[id]": ProfilerPage<(c: Ctx) => Promise<{
+    report: Awaited<ReturnType<ProfilerDeps["report_view"]>>;
+    base: string;
+    login: null;
+    exists: boolean;
+  } | {
+    report: null;
+    base: string;
+    login: string | null;
+    exists: boolean;
+  }>>;
+  readonly "/report/[id].json": {
+    readonly GET: CtxFn<Promise<Response>>;
+    readonly POST: CtxFn<Promise<Response>>;
+  };
+  readonly "/report/[id].html": {
+    readonly GET: CtxFn<Promise<Response>>;
+    readonly POST: CtxFn<Promise<Response>>;
+  };
+  readonly "/report/[id].dump": {
+    readonly GET: CtxFn<Promise<Response>>;
+    readonly POST: CtxFn<Promise<Response>>;
+  };
+  readonly "/report/[id].ogp": {
+    readonly POST: CtxFn<Promise<Response>>;
+  };
+  readonly "/report/[id]/raw": {
+    readonly GET: CtxFn<Promise<Response>>;
+  };
+  readonly "/compare/[a]/[b]": ProfilerPage<(c: Ctx) => ReturnType<ProfilerDeps["compare"]>>;
+  readonly "/replay/[id]": {
+    readonly GET: CtxFn<Promise<Response>>;
+  };
+  readonly "/site": ProfilerPage<(c: Ctx) => ReturnType<ProfilerDeps["site"]>>;
+  readonly "/source": {
+    readonly GET: CtxFn<Promise<Response>>;
+  };
+}>;
+/** The whole profiler route tree as a typed `path → { data, params, form, search }` map — components index it. */
+export type ProfilerRoutes = ReturnType<typeof build_profiler_router>["$infer"];
+export {};

package/dist/profiler/profiler-router.js

@@ -0,0 +1,113 @@
+import { error, page, routes } from "@ogygia/router";
+import Dashboard from "./ui/Dashboard.svelte";
+import Report from "./ui/Report.svelte";
+import Run from "./ui/Run.svelte";
+import Login from "./ui/Login.svelte";
+import Upload from "./ui/Upload.svelte";
+import Message from "./ui/Message.svelte";
+import Compare from "./ui/Compare.svelte";
+import Site from "./ui/Site.svelte";
+// src/profiler/profiler-router.ts
+/**
+* The profiler's route tree — dogfood for `@ogygia/router` v2 (internal/notes/router-v2.md). Extracted
+* from ProfilerHost so its `$infer` type is importable: the host passes bound methods across the typed
+* `ProfilerDeps` boundary, and each UI component types its props by indexing the map —
+* `let { data }: ProfilerRoutes['/'] = $props()` — instead of re-declaring the shape.
+*
+* v2 idioms on show: a flat table (the whole sitemap in one glance), the auth GUARD as the table-wide
+* `load` (no chrome component — the profiler pages render their own Shell), a root `error` boundary,
+* bare `{ GET }` endpoint objects, and thrown `error()` for the expired-report 404s.
+*
+* The one unavoidable ceremony is `V` below: each UI component types its props by indexing
+* `ProfilerRoutes` (`ProfilerRoutes['/']`), so referencing a component VALUE here — while `$infer`
+* (hence `ProfilerRoutes`) is still being computed — makes svelte2tsx resolve that component's own
+* props mid-computation and report `$$ComponentProps circularly references itself` (props then fall
+* back to `any`, silently). Erasing the refs to a bare `Component` record breaks the self-reference;
+* `$infer` still comes from the LOADS, which keep their real return types. This is the same reason Kit
+* generates `./$types` in a component-free module — a programmatic router has no codegen to hide it.
+*/
+/** Prop-erased component refs — see the file header. Referenced as `V.Dashboard` in the table so
+*  `$infer` never resolves a component's own (self-referential) props. Real types survive on `data`. */
+const V = {
+	Dashboard,
+	Report,
+	Run,
+	Login,
+	Upload,
+	Message,
+	Compare,
+	Site
+};
+/** Shared lookup for the report representations: the stored report (memory or the storage backend),
+*  or a thrown 404. */
+async function report_or_404(d, id, fn) {
+	const s = await d.report_load(id);
+	if (!s) error(404, "That report has expired.");
+	return await fn(s);
+}
+/** Build the profiler router. Auth is the table-wide `load` (a redirect/deny short-circuits every
+*  route; on allow it seeds `{ base }`); thrown `error()` renders the root `Message` boundary.
+*  `/report/[id]` is PUBLIC (a share `#fragment` decrypts client-side); its `.json`/`.dump`/`/raw`
+*  siblings keep the suffix so they stay behind the guard's server-data gate. Endpoints are
+*  the plain `{ GET }` object form (bare handlers; `c.params.id` reads from the table key). */
+function build_profiler_router(d) {
+	return routes({
+		"/": page(V.Dashboard, { load: (c) => d.dashboard(c) }),
+		"/run": page(V.Run, { load: (c) => d.run_page(c) }),
+		"/page": { GET: (c) => d.record_page(c) },
+		"/reset": { GET: (c) => d.reset(c) },
+		"/status.json": { GET: (c) => c.json(d.status(c)) },
+		"/beacon": { POST: (c) => d.beacon(c) },
+		"/window/start": { POST: (c) => d.window_start(c) },
+		"/window/stop": { POST: (c) => d.window_stop(c) },
+		"/login": page(V.Login, {
+			load: (c) => d.login_props(c),
+			actions: { default: (c) => d.login(c) }
+		}),
+		"/logout": { GET: (c) => d.logout(c) },
+		"/view": page(V.Upload, {
+			load: () => ({ base: d.base }),
+			actions: { default: (c) => d.upload(c) }
+		}),
+		"/reports.json": { GET: async (c) => c.json(await d.list_stored()) },
+		"/report/[id]": page(V.Report, { load: async (c) => {
+			const stored = await d.authed(c) ? await d.report_load(c.params.id) : d.report_stored(c.params.id);
+			if (stored && await d.authed(c)) return {
+				report: await d.report_view(stored),
+				base: d.base,
+				login: null,
+				exists: true
+			};
+			return {
+				report: null,
+				base: d.base,
+				login: d.login_url(c),
+				exists: !!stored
+			};
+		} }),
+		"/report/[id].json": {
+			GET: (c) => report_or_404(d, c.params.id, d.report_json),
+			POST: (c) => d.report_posted(c, "json")
+		},
+		"/report/[id].html": {
+			GET: (c) => report_or_404(d, c.params.id, (s) => d.report_html(s, c)),
+			POST: (c) => d.report_posted(c, "html")
+		},
+		"/report/[id].dump": {
+			GET: (c) => report_or_404(d, c.params.id, d.report_dump_json),
+			POST: (c) => d.report_posted(c, "dump")
+		},
+		"/report/[id].ogp": { POST: (c) => d.report_posted(c, "ogp") },
+		"/report/[id]/raw": { GET: (c) => report_or_404(d, c.params.id, d.report_raw) },
+		"/compare/[a]/[b]": page(V.Compare, { load: (c) => d.compare(c.params.a, c.params.b) }),
+		"/replay/[id]": { GET: (c) => d.replay(c.params.id, c) },
+		"/site": page(V.Site, { load: (c) => d.site(c) }),
+		"/source": { GET: (c) => d.source(c) }
+	}, {
+		base: d.base,
+		error: V.Message,
+		load: async (c) => await d.auth_guard(c) ?? { base: d.base },
+		miss: () => error(404, "Unknown profiler page.")
+	});
+}
+export { build_profiler_router };

package/dist/profiler/refresh-stub.d.ts

@@ -0,0 +1,2 @@
+/** The path a redirect stub sends the visitor to (`/to?q`), or null when `body` is not one. */
+export declare function refresh_target(body: string, origin: string): string | null;

package/dist/profiler/refresh-stub.js

@@ -0,0 +1,37 @@
+// src/profiler/refresh-stub.ts
+/**
+* A REDIRECT WRITTEN AS A PAGE. A prerendered route that redirects has no server to answer 3xx, so
+* the build writes a stub in its place — `<meta http-equiv="refresh" content="0;url=/to">` (and a
+* script that sets `location.href`) — and the host answers it 200. Profiled as it is, it read as
+* "only 118 bytes: not a render". The page it sends the visitor to is the one to profile.
+*/
+/** the largest body read as a stub: a real page with a refresh tag is a page, not a redirect */
+const STUB_MAX_BYTES = 2048;
+/** The path a redirect stub sends the visitor to (`/to?q`), or null when `body` is not one. */
+function refresh_target(body, origin) {
+	if (!body || body.length > STUB_MAX_BYTES) return null;
+	const lower = body.toLowerCase();
+	const at = lower.indexOf("http-equiv=\"refresh\"");
+	if (at < 0) return null;
+	const open = lower.lastIndexOf("<meta", at);
+	const close = lower.indexOf(">", at);
+	if (open < 0 || close < 0) return null;
+	const tag = body.slice(open, close);
+	const c = tag.toLowerCase().indexOf("content=\"");
+	if (c < 0) return null;
+	const content = tag.slice(c + 9, tag.indexOf("\"", c + 9));
+	const u = content.toLowerCase().indexOf("url=");
+	if (u < 0) return null;
+	let to = content.slice(u + 4).trim();
+	const q = to[0];
+	if (q === "'" || q === "\"") to = to.endsWith(q) && to.length > 1 ? to.slice(1, -1) : to.slice(1);
+	if (!to) return null;
+	try {
+		const url = new URL(to, origin);
+		if (url.origin !== new URL(origin).origin) return null;
+		return url.pathname + url.search;
+	} catch {
+		return null;
+	}
+}
+export { refresh_target };