okengine 0.6.0 → 0.7.0

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,
@@ -56,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. */
@@ -489,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;
@@ -511,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.
@@ -525,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,} \|/);
   });
 });

package/src/runtime/dev-request-log.test.ts

@@ -3,7 +3,11 @@
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
-import { isSilentDevRequest, shouldLogDevRequests } from "./dev-request-log.ts";
+import {
+  failureDetailFromResponse,
+  isSilentDevRequest,
+  shouldLogDevRequests,
+} from "./dev-request-log.ts";
 
 describe("dev-request-log", () => {
   const prev = process.env.OKE_DEV_REQUEST_LOG;
@@ -27,4 +31,19 @@ describe("dev-request-log", () => {
     expect(isSilentDevRequest("GET", "/_oke/client.json")).toBe(true);
     expect(isSilentDevRequest("POST", "/console/flows")).toBe(false);
   });
+
+  test("failureDetailFromResponse reads error.message from envelope", async () => {
+    const res = Response.json(
+      {
+        data: null,
+        error: {
+          code: "ClaimFailed",
+          data: { reason: "password_policy" },
+          message: "Password needs at least 12 characters, including a letter and a number.",
+        },
+      },
+      { status: 400 },
+    );
+    expect(await failureDetailFromResponse(res)).toMatch(/12 characters/);
+  });
 });

package/src/runtime/dev-request-log.ts

@@ -52,6 +52,8 @@ export type DevRequestLogInput = {
   readonly flow?: string;
   readonly status: number;
   readonly ms: number;
+  /** Human failure detail (error.message / code) for 4xx/5xx. */
+  readonly detail?: string;
 };
 
 /**
@@ -70,6 +72,39 @@ export function isSilentDevRequest(method: string, path: string): boolean {
   return /\.(?:js|css|map|svg|png|ico|woff2?|ttf|webp)$/i.test(path);
 }
 
+/**
+ * Extract a short failure detail from an OKE JSON envelope body.
+ *
+ * @param response - HTTP response (cloned; original body stays readable)
+ */
+export async function failureDetailFromResponse(response: Response): Promise<string | undefined> {
+  if (response.status < 400) return undefined;
+  try {
+    const body: unknown = await response.clone().json();
+    if (body === null || typeof body !== "object" || !("error" in body)) return undefined;
+    const error = (body as { error: unknown }).error;
+    if (error === null || typeof error !== "object") return undefined;
+    const rec = error as { message?: unknown; code?: unknown; data?: unknown };
+    if (typeof rec.message === "string" && rec.message.trim().length > 0) {
+      return rec.message.trim();
+    }
+    if (
+      rec.data !== null &&
+      typeof rec.data === "object" &&
+      "reason" in rec.data &&
+      typeof (rec.data as { reason: unknown }).reason === "string"
+    ) {
+      const reason = (rec.data as { reason: string }).reason;
+      const code = typeof rec.code === "string" ? rec.code : "Error";
+      return `${code}: ${reason}`;
+    }
+    if (typeof rec.code === "string") return rec.code;
+  } catch {
+    // non-JSON error bodies stay status-only
+  }
+  return undefined;
+}
+
 /**
  * Print one request line when {@link shouldLogDevRequests} is on.
  *
@@ -86,6 +121,7 @@ export function logDevRequest(input: DevRequestLogInput): void {
       flow: input.flow,
       status: input.status,
       ms: input.ms,
+      detail: input.detail,
     }),
   );
 }
@@ -115,6 +151,7 @@ export async function timedDevFetch(
   const url = new URL(request.url);
   const method = request.method.toUpperCase();
   const response = await handle(request);
+  const detail = await failureDetailFromResponse(response);
   logDevRequest({
     surface: options.surface ?? currentDevSurface(),
     method,
@@ -122,6 +159,7 @@ export async function timedDevFetch(
     flow: options.resolveFlow?.(request, response),
     status: response.status,
     ms: Math.round(performance.now() - started),
+    detail,
   });
   return response;
 }

package/src/term.test.ts

@@ -125,6 +125,21 @@ describe("term", () => {
     expect(out).not.toMatch(/\u001b\[/);
   });
 
+  test("formatRequestLine prints failure detail under 4xx/5xx", () => {
+    const out = formatRequestLine({
+      surface: "Console",
+      method: "POST",
+      path: "/console/setup/claim",
+      flow: "console.setup.claim",
+      status: 400,
+      ms: 1,
+      detail: "Password needs at least 12 characters, including a letter and a number.",
+      color: false,
+    });
+    expect(out).toContain("400");
+    expect(out).toContain("↳ Password needs at least 12 characters");
+  });
+
   test("formatStackSummary is scannable", () => {
     const out = formatStackSummary({
       project: "oke-dev-a3f791",

package/src/term.ts

@@ -300,6 +300,8 @@ export function formatRequestLine(options: {
   /** Instant for date/time columns (default now). */
   readonly at?: Date;
   readonly color?: boolean;
+  /** Failure detail printed on a follow-up line (4xx/5xx). */
+  readonly detail?: string;
 }): string {
   const s = termStyle(options.color ?? termColorEnabled());
   const at = options.at ?? new Date();
@@ -323,7 +325,7 @@ export function formatRequestLine(options: {
   const path = options.path.length > 28 ? `${options.path.slice(0, 27)}…` : options.path.padEnd(28);
   const flow = (options.flow ?? "—").padEnd(22);
   const ms = `${options.ms}ms`.padStart(6);
-  return (
+  const main =
     `${surfaceColor}●${s.reset}  ` +
     `${surfaceColor}${options.surface.padEnd(7)}${s.reset}  ` +
     `${methodColor}${method}${s.reset} ` +
@@ -332,8 +334,11 @@ export function formatRequestLine(options: {
     `${s.dim}${ms}${s.reset}  ` +
     `${statusColor}${options.status}${s.reset}  ` +
     `${s.dim}${date}${s.reset}  ` +
-    `${s.dim}${time}${s.reset}\n`
-  );
+    `${s.dim}${time}${s.reset}\n`;
+  const detail = options.detail?.trim();
+  if (!detail || options.status < 400) return main;
+  const clipped = detail.length > 120 ? `${detail.slice(0, 119)}…` : detail;
+  return `${main}${s.dim}   ↳ ${clipped}${s.reset}\n`;
 }
 
 /**