okengine 0.5.1 → 0.6.1

package/src/release/exports.test.ts

@@ -9,7 +9,9 @@ import {
   exportBudgetLabel,
   isMeasurableDriverFile,
   listDriverModules,
+  OFFICIAL_PLUGIN_BUDGETS,
   resolveExportBudgetTargets,
+  resolvePluginBudgetTargets,
 } from "./exports.ts";
 
 const ROOT = resolve(import.meta.dir, "../..");
@@ -29,12 +31,32 @@ describe("export budget targets", () => {
     expect(exportBudgetLabel(".")).toBe("okengine");
     expect(exportBudgetLabel("./channel")).toBe("channel");
     expect(exportBudgetLabel("./drivers/postgres")).toBe("postgres");
+    expect(exportBudgetLabel("./plugins/cors")).toBe("cors");
     expect(exportBudgetGroup(".")).toBe("exports");
     expect(exportBudgetGroup("./channel")).toBe("exports");
+    expect(exportBudgetGroup("./plugins")).toBe("exports");
+    expect(exportBudgetGroup("./plugins/cors")).toBe("plugins");
     expect(exportBudgetGroup("./drivers")).toBe("drivers");
     expect(exportBudgetGroup("./drivers/postgres")).toBe("drivers");
   });
 
+  test("official plugin catalogue files exist and resolve uniquely", async () => {
+    const plugins = resolvePluginBudgetTargets();
+    expect(plugins.length).toBe(OFFICIAL_PLUGIN_BUDGETS.length);
+    expect(new Set(plugins.map((t) => t.id)).size).toBe(plugins.length);
+
+    for (const plugin of OFFICIAL_PLUGIN_BUDGETS) {
+      const path = join(ROOT, "src/plugins", plugin.file);
+      expect(await Bun.file(path).exists()).toBe(true);
+      const target = plugins.find((t) => t.label === plugin.name);
+      expect(target).toBeDefined();
+      expect(target!.id).toBe(`export:./plugins/${plugin.name}`);
+      expect(target!.group).toBe("plugins");
+      expect(target!.category).toBe(plugin.category);
+      expect(target!.entry).toBe(path);
+    }
+  });
+
   test("every non-glob package export and every driver module is covered", async () => {
     const pkg = (await Bun.file(join(ROOT, "package.json")).json()) as {
       exports: Record<string, string>;
@@ -65,6 +87,10 @@ describe("export budget targets", () => {
       expect(target!.entry).toBe(join(ROOT, "src/drivers", file));
     }
 
+    for (const plugin of OFFICIAL_PLUGIN_BUDGETS) {
+      expect(bySubpath.get(`./plugins/${plugin.name}`)).toBeDefined();
+    }
+
     // No duplicates.
     expect(new Set(targets.map((t) => t.id)).size).toBe(targets.length);
   });

package/src/release/exports.ts

@@ -2,22 +2,37 @@
  * Resolve published `package.json` exports into measurable bundle entries.
  *
  * Expands `./drivers/*` to concrete driver modules (tree-shaken subpaths).
+ * Official `okengine/plugins` named modules are sampled separately (not published
+ * as `./plugins/*` subpaths).
  */
 
 import { readdir } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
+import {
+  OFFICIAL_PLUGIN_BUDGETS,
+  type OfficialPluginBudget,
+  type PluginBudgetCategory,
+} from "./official-plugins.ts";
+
+export {
+  OFFICIAL_PLUGIN_BUDGETS,
+  PLUGIN_BUDGET_CATEGORIES,
+  type OfficialPluginBudget,
+  type PluginBudgetCategory,
+} from "./official-plugins.ts";
 
 const ROOT = resolve(import.meta.dir, "../..");
 const DRIVERS_DIR = join(ROOT, "src/drivers");
+const PLUGINS_DIR = join(ROOT, "src/plugins");
 
 /** Report / snapshot group for a budget sample. */
-export type BudgetGroup = "core" | "exports" | "drivers";
+export type BudgetGroup = "core" | "exports" | "plugins" | "drivers";
 
 /** One published subpath ready for gzip measurement. */
 export interface ExportBudgetTarget {
   /** Sample id — `export:<subpath>`. */
   readonly id: string;
-  /** Package subpath (`.` or `./store`, `./drivers/postgres`, …). */
+  /** Package subpath (`.` or `./store`, `./drivers/postgres`, `./plugins/cors`, …). */
   readonly subpath: string;
   /** Short human label (`channel`, `postgres`, `okengine`, …). */
   readonly label: string;
@@ -25,18 +40,23 @@ export interface ExportBudgetTarget {
   readonly group: BudgetGroup;
   /** Absolute path to the TypeScript entry. */
   readonly entry: string;
+  /** Docs category when `group` is `plugins`. */
+  readonly category?: PluginBudgetCategory;
 }
 
 /**
  * Short display name for a package subpath.
  *
- * @param subpath - `.` / `./channel` / `./drivers/postgres`
+ * @param subpath - `.` / `./channel` / `./drivers/postgres` / `./plugins/cors`
  */
 export function exportBudgetLabel(subpath: string): string {
   if (subpath === ".") return "okengine";
   if (subpath.startsWith("./drivers/")) {
     return subpath.slice("./drivers/".length);
   }
+  if (subpath.startsWith("./plugins/")) {
+    return subpath.slice("./plugins/".length);
+  }
   if (subpath.startsWith("./")) return subpath.slice(2);
   return subpath;
 }
@@ -50,6 +70,10 @@ export function exportBudgetGroup(subpath: string): BudgetGroup {
   if (subpath === "./drivers" || subpath.startsWith("./drivers/")) {
     return "drivers";
   }
+  // Named plugin modules (not the `./plugins` barrel — that stays in exports).
+  if (subpath.startsWith("./plugins/")) {
+    return "plugins";
+  }
   return "exports";
 }
 
@@ -82,6 +106,30 @@ export async function listDriverModules(driversDir = DRIVERS_DIR): Promise<reado
   return entries.filter(isMeasurableDriverFile).sort((a, b) => a.localeCompare(b));
 }
 
+/**
+ * Resolve official plugin modules into measurement targets.
+ *
+ * @param options - Override plugins dir (tests)
+ */
+export function resolvePluginBudgetTargets(options?: {
+  readonly pluginsDir?: string;
+  readonly catalogue?: readonly OfficialPluginBudget[];
+}): readonly ExportBudgetTarget[] {
+  const pluginsDir = options?.pluginsDir ?? PLUGINS_DIR;
+  const catalogue = options?.catalogue ?? OFFICIAL_PLUGIN_BUDGETS;
+  return catalogue.map((plugin) => {
+    const subpath = `./plugins/${plugin.name}`;
+    return {
+      id: `export:${subpath}`,
+      subpath,
+      label: plugin.name,
+      group: "plugins" as const,
+      entry: join(pluginsDir, plugin.file),
+      category: plugin.category,
+    };
+  });
+}
+
 /**
  * Resolve every published export into a stable, sorted measurement target list.
  *
@@ -91,12 +139,14 @@ export async function resolveExportBudgetTargets(options?: {
   readonly root?: string;
   readonly pkg?: PackageExports;
   readonly driversDir?: string;
+  readonly pluginsDir?: string;
 }): Promise<readonly ExportBudgetTarget[]> {
   const root = options?.root ?? ROOT;
   const pkg =
     options?.pkg ?? ((await Bun.file(join(root, "package.json")).json()) as PackageExports);
   const exportsMap = pkg.exports ?? {};
   const driversDir = options?.driversDir ?? join(root, "src/drivers");
+  const pluginsDir = options?.pluginsDir ?? join(root, "src/plugins");
 
   const targets: ExportBudgetTarget[] = [];
 
@@ -121,6 +171,8 @@ export async function resolveExportBudgetTargets(options?: {
     targets.push(targetFor(subpath, resolve(root, entryRel)));
   }
 
+  targets.push(...resolvePluginBudgetTargets({ pluginsDir }));
+
   targets.sort((a, b) => {
     const g = groupOrder(a.group) - groupOrder(b.group);
     if (g !== 0) return g;
@@ -129,6 +181,12 @@ export async function resolveExportBudgetTargets(options?: {
     if (b.subpath === "./drivers") return 1;
     if (a.subpath === ".") return -1;
     if (b.subpath === ".") return 1;
+    // Catalogue order for plugins (docs category order).
+    if (a.group === "plugins" && b.group === "plugins") {
+      const ai = OFFICIAL_PLUGIN_BUDGETS.findIndex((p) => p.name === a.label);
+      const bi = OFFICIAL_PLUGIN_BUDGETS.findIndex((p) => p.name === b.label);
+      if (ai !== -1 && bi !== -1) return ai - bi;
+    }
     return a.label.localeCompare(b.label);
   });
   return targets;
@@ -146,6 +204,7 @@ function targetFor(subpath: string, entry: string): ExportBudgetTarget {
 
 function groupOrder(group: BudgetGroup): number {
   if (group === "exports") return 0;
-  if (group === "drivers") return 1;
-  return 2;
+  if (group === "plugins") return 1;
+  if (group === "drivers") return 2;
+  return 3;
 }

package/src/release/index.ts

@@ -7,9 +7,14 @@ export {
   exportBudgetLabel,
   isMeasurableDriverFile,
   listDriverModules,
+  OFFICIAL_PLUGIN_BUDGETS,
+  PLUGIN_BUDGET_CATEGORIES,
   resolveExportBudgetTargets,
+  resolvePluginBudgetTargets,
   type BudgetGroup,
   type ExportBudgetTarget,
+  type OfficialPluginBudget,
+  type PluginBudgetCategory,
 } from "./exports.ts";
 
 export {

package/src/release/measure.exports.test.ts

@@ -31,7 +31,7 @@ describe("export gzip budgets", () => {
     );
   });
 
-  test("formatBudgetsReport groups Core / Exports / Drivers with short names", () => {
+  test("formatBudgetsReport groups Core / Exports / Plugins / Drivers with short names", () => {
     const snapshot: BudgetsSnapshot = {
       measuredAt: "2026-07-25T00:00:00.000Z",
       version: "0.0.0",
@@ -56,6 +56,16 @@ describe("export gzip budgets", () => {
           group: "exports",
           ok: true,
         },
+        {
+          id: "export:./plugins/cors",
+          label: "cors",
+          value: 100,
+          limit: 200,
+          unit: "bytes",
+          gate: "regression",
+          group: "plugins",
+          ok: true,
+        },
         {
           id: "export:./drivers/postgres",
           label: "postgres",
@@ -71,8 +81,10 @@ describe("export gzip budgets", () => {
     const report = formatBudgetsReport(snapshot);
     expect(report).toContain("\nCore\n");
     expect(report).toContain("\nExports\n");
+    expect(report).toContain("\nPlugins\n");
     expect(report).toContain("\nDrivers\n");
     expect(report).toContain("[ok] channel:");
+    expect(report).toContain("[ok] cors:");
     expect(report).toContain("[ok] postgres:");
     expect(report).not.toContain("regression Export");
     expect(report).not.toContain("./channel");

package/src/release/measure.ts

@@ -6,7 +6,12 @@ import { mkdtemp, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { createRouter } from "../kernel/router.ts";
-import { type BudgetGroup, resolveExportBudgetTargets } from "./exports.ts";
+import {
+  type BudgetGroup,
+  OFFICIAL_PLUGIN_BUDGETS,
+  PLUGIN_BUDGET_CATEGORIES,
+  resolveExportBudgetTargets,
+} from "./exports.ts";
 import {
   CLIENT_BUDGET_BYTES,
   COLD_START_BUDGET_MS,
@@ -24,7 +29,14 @@ const BUDGETS_JSON_PATH = resolve(ROOT, "budgets.json");
  * Deps measured separately from OKE code in export samples.
  * Edge/client absolute gates keep the historical smaller external list.
  */
-const BUILD_EXTERNALS = ["@duckdb/node-api", "@duckdb/*"] as const;
+const BUILD_EXTERNALS = [
+  "@duckdb/node-api",
+  "@duckdb/*",
+  // ICU MessageFormat — adopted FormatJS runtime; kept out of the edge
+  // micro-bundle the same way other heavy deps are measured separately.
+  "intl-messageformat",
+  "@formatjs/*",
+] as const;
 
 /** Heavy optional / peer packages — not counted in export:* gzip samples. */
 const EXPORT_BUILD_EXTERNALS = [
@@ -49,9 +61,18 @@ export type BudgetGate = "absolute" | "regression";
 const GROUP_HEADINGS: Readonly<Record<BudgetGroup, string>> = {
   core: "Core",
   exports: "Exports",
+  plugins: "Plugins",
   drivers: "Drivers",
 };
 
+/** Docs category → markdown subheading under Plugins. */
+const PLUGIN_CATEGORY_HEADINGS: Readonly<Record<string, string>> = {
+  auth: "Auth",
+  security: "Security",
+  ops: "Ops",
+  perf: "Perf",
+};
+
 /** One measured budget sample. */
 export interface BudgetSample {
   /** Stable metric id. */
@@ -482,13 +503,13 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
 }
 
 /**
- * Format a snapshot for CI logs (Core / Exports / Drivers sections).
+ * Format a snapshot for CI logs (Core / Exports / Plugins / Drivers).
  *
  * @param snapshot - Measured budgets
  */
 export function formatBudgetsReport(snapshot: BudgetsSnapshot): string {
   const lines = [`okengine budgets v${snapshot.version} @ ${snapshot.measuredAt}`];
-  const order: readonly BudgetGroup[] = ["core", "exports", "drivers"];
+  const order: readonly BudgetGroup[] = ["core", "exports", "plugins", "drivers"];
   for (const group of order) {
     const rows = snapshot.budgets.filter((b) => b.group === group);
     if (rows.length === 0) continue;
@@ -504,6 +525,28 @@ export function formatBudgetsReport(snapshot: BudgetsSnapshot): string {
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * Markdown table with column widths padded so `oxfmt` is a no-op.
+ * Compact `|---|` tables get realigned by oxfmt and make Format fail after
+ * every `bun run budgets` refresh.
+ *
+ * @param headers - Column headers (use `""` for an unnamed first column)
+ * @param rows - Body cells
+ */
+export function formatMarkdownTable(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[],
+): string[] {
+  const widths = headers.map((header, i) =>
+    Math.max(header.length, ...rows.map((row) => (row[i] ?? "").length)),
+  );
+  const cell = (value: string, i: number): string => value.padEnd(widths[i]!);
+  const line = (cells: readonly string[]): string =>
+    `| ${cells.map((value, i) => cell(value, i)).join(" | ")} |`;
+  const sep = `| ${widths.map((w) => "-".repeat(w)).join(" | ")} |`;
+  return [line(headers), sep, ...rows.map((row) => line(row))];
+}
+
 /**
  * Full markdown document for [`BUDGETS.md`](../../BUDGETS.md).
  * Written by `bun run budgets` — do not edit the tables by hand.
@@ -518,24 +561,51 @@ export function formatBudgetsMarkdown(snapshot: BudgetsSnapshot): string {
     "",
     `_okengine v${snapshot.version} · measured ${snapshot.measuredAt}_`,
     "",
-    "Core rows are absolute AGENTS caps. Exports and Drivers fail on regression vs the prior [`budgets.json`](budgets.json) (max +256 B or +2%). Export gzip excludes peers/optionals (`zod`, `sently`, `oxc-parser`, `ajv`).",
+    "Core rows are absolute AGENTS caps. Exports, Plugins, and Drivers fail on regression vs the prior [`budgets.json`](budgets.json) (max +256 B or +2%). Export gzip excludes peers/optionals (`zod`, `sently`, `oxc-parser`, `ajv`).",
   ];
-  const order: readonly BudgetGroup[] = ["core", "exports", "drivers"];
+  const order: readonly BudgetGroup[] = ["core", "exports", "plugins", "drivers"];
   for (const group of order) {
     const rows = snapshot.budgets.filter((b) => b.group === group);
     if (rows.length === 0) continue;
     const limitCol = group === "core" ? "Limit" : "Ceiling";
     lines.push("");
     lines.push(`## ${GROUP_HEADINGS[group]}`);
-    lines.push("");
-    lines.push(`| | Measured | ${limitCol} |`);
-    lines.push("|---|---|---|");
-    for (const b of rows) {
-      const mark = b.ok ? "" : " **FAIL**";
-      lines.push(
-        `| ${b.label}${mark} | ${formatValue(b.value, b.unit)} | ${formatValue(b.limit, b.unit)} |`,
-      );
+    if (group === "plugins") {
+      for (const category of PLUGIN_BUDGET_CATEGORIES) {
+        const names = new Set(
+          OFFICIAL_PLUGIN_BUDGETS.filter((p) => p.category === category).map((p) => p.name),
+        );
+        const catRows = rows.filter((b) => names.has(b.label));
+        if (catRows.length === 0) continue;
+        lines.push("");
+        lines.push(`### ${PLUGIN_CATEGORY_HEADINGS[category] ?? category}`);
+        lines.push("");
+        lines.push(
+          ...formatMarkdownTable(
+            ["", "Measured", limitCol],
+            catRows.map((b) => {
+              const mark = b.ok ? "" : " **FAIL**";
+              return [
+                `${b.label}${mark}`,
+                formatValue(b.value, b.unit),
+                formatValue(b.limit, b.unit),
+              ];
+            }),
+          ),
+        );
+      }
+      continue;
     }
+    lines.push("");
+    lines.push(
+      ...formatMarkdownTable(
+        ["", "Measured", limitCol],
+        rows.map((b) => {
+          const mark = b.ok ? "" : " **FAIL**";
+          return [`${b.label}${mark}`, formatValue(b.value, b.unit), formatValue(b.limit, b.unit)];
+        }),
+      ),
+    );
   }
   return `${lines.join("\n")}\n`;
 }

package/src/release/official-plugins.ts

@@ -0,0 +1,46 @@
+/**
+ * Official `okengine/plugins` named exports measured for CI budgets.
+ * Categories match `site/content/docs/plugins/index.mdx`.
+ * Keep in sync with the docs catalogue — landing + budgets both read this.
+ */
+
+/** Docs / landing category for an official plugin. */
+export type PluginBudgetCategory = "auth" | "security" | "ops" | "perf";
+
+/** One official plugin entry measured as `export:./plugins/<name>`. */
+export type OfficialPluginBudget = {
+  /** Named export from `okengine/plugins`. */
+  readonly name: string;
+  /** Basename under `src/plugins/` (e.g. `magic-link.ts`). */
+  readonly file: string;
+  /** Docs category. */
+  readonly category: PluginBudgetCategory;
+};
+
+/** Category display order (docs index). */
+export const PLUGIN_BUDGET_CATEGORIES: readonly PluginBudgetCategory[] = [
+  "auth",
+  "security",
+  "ops",
+  "perf",
+] as const;
+
+/**
+ * Canonical official plugins — membership, file mapping, and grouping.
+ * Order within a category is docs order; landing may re-sort by size.
+ */
+export const OFFICIAL_PLUGIN_BUDGETS: readonly OfficialPluginBudget[] = [
+  { name: "username", file: "username.ts", category: "auth" },
+  { name: "anonymous", file: "anonymous.ts", category: "auth" },
+  { name: "magicLink", file: "magic-link.ts", category: "auth" },
+  { name: "emailOtp", file: "email-otp.ts", category: "auth" },
+  { name: "phoneNumber", file: "phone-number.ts", category: "auth" },
+  { name: "twoFactor", file: "two-factor.ts", category: "auth" },
+  { name: "passkey", file: "passkey.ts", category: "auth" },
+  { name: "headers", file: "headers.ts", category: "security" },
+  { name: "cors", file: "cors.ts", category: "security" },
+  { name: "csrf", file: "csrf.ts", category: "security" },
+  { name: "ipAllowlist", file: "ip-allowlist.ts", category: "security" },
+  { name: "maintenanceMode", file: "maintenance-mode.ts", category: "ops" },
+  { name: "compression", file: "compression.ts", category: "perf" },
+] as const;

package/src/release/readme.test.ts

@@ -36,6 +36,26 @@ describe("budgets markdown", () => {
           group: "exports",
           ok: true,
         },
+        {
+          id: "export:./plugins/cors",
+          label: "cors",
+          value: 2048,
+          limit: 2304,
+          unit: "bytes",
+          gate: "regression",
+          group: "plugins",
+          ok: true,
+        },
+        {
+          id: "export:./plugins/username",
+          label: "username",
+          value: 3072,
+          limit: 3328,
+          unit: "bytes",
+          gate: "regression",
+          group: "plugins",
+          ok: true,
+        },
         {
           id: "export:./drivers/postgres",
           label: "postgres",
@@ -52,10 +72,18 @@ describe("budgets markdown", () => {
     expect(md.startsWith("# Budgets\n")).toBe(true);
     expect(md).toContain("## Core");
     expect(md).toContain("## Exports");
+    expect(md).toContain("## Plugins");
+    expect(md).toContain("### Auth");
+    expect(md).toContain("### Security");
     expect(md).toContain("## Drivers");
-    expect(md).toContain("| channel |");
-    expect(md).toContain("| postgres |");
+    expect(md).toMatch(/\|\s*channel\s*\|/);
+    expect(md).toMatch(/\|\s*cors\s*\|/);
+    expect(md).toMatch(/\|\s*username\s*\|/);
+    expect(md).toMatch(/\|\s*postgres\s*\|/);
     expect(md).toContain("[`budgets.json`](budgets.json)");
     expect(md).not.toContain("./channel");
+    // oxfmt-aligned separators (not compact `|---|---|---|`) so Format stays green
+    expect(md).not.toContain("|---|---|---|");
+    expect(md).toMatch(/\| -{3,} \| -{3,} \| -{3,} \|/);
   });
 });