okengine 0.1.6 → 0.2.2

package/src/mcp/docs-tools.ts

@@ -0,0 +1,143 @@
+/**
+ * Read-only docs MCP tools — search and fetch documentation pages.
+ *
+ * Every return goes through {@link asData}. No write tools, no auth scopes.
+ */
+
+import { asData, type McpDataEnvelope } from "./data.ts";
+import type { DocsIndex } from "./docs-index.ts";
+
+/** Result of a docs tool call. */
+export type DocsToolCallResult =
+  | { readonly ok: true; readonly data: McpDataEnvelope }
+  | {
+      readonly ok: false;
+      readonly code: "invalid" | "not-found";
+      readonly message: string;
+      readonly data: McpDataEnvelope;
+    };
+
+/** Tool descriptor exposed via `tools/list`. */
+export interface DocsToolDescriptor {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+}
+
+/** Docs MCP tool catalogue. */
+export const DOCS_MCP_TOOLS: readonly DocsToolDescriptor[] = [
+  {
+    name: "oke.docs.search",
+    description:
+      "Search okengine documentation pages by keyword. Returns slug, title, url, and excerpt.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+        limit: {
+          type: "number",
+          description: "Max results (default 20)",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "oke.docs.get",
+    description:
+      "Fetch a documentation page by slug or content path. Returns source-identical markdown (YAML frontmatter stripped).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: {
+          type: "string",
+          description:
+            "Page slug (e.g. get-started/introduction) or path (…/introduction.mdx)",
+        },
+      },
+      required: ["slug"],
+      additionalProperties: false,
+    },
+  },
+] as const;
+
+/**
+ * Create the docs tool runtime bound to an index.
+ *
+ * @param index - Loaded docs catalogue
+ */
+export function createDocsToolRuntime(index: DocsIndex): {
+  readonly listTools: () => readonly DocsToolDescriptor[];
+  readonly callTool: (
+    name: string,
+    args: Record<string, unknown>,
+  ) => DocsToolCallResult;
+} {
+  return {
+    listTools: () => DOCS_MCP_TOOLS,
+    callTool(name, args) {
+      if (name === "oke.docs.search") {
+        const query = args.query;
+        if (typeof query !== "string" || query.trim().length === 0) {
+          return {
+            ok: false,
+            code: "invalid",
+            message: "query must be a non-empty string",
+            data: asData({ reason: "invalid-query" }, "error"),
+          };
+        }
+        const limit =
+          typeof args.limit === "number" && Number.isFinite(args.limit)
+            ? Math.max(1, Math.min(100, Math.floor(args.limit)))
+            : 20;
+        const hits = index.search(query, limit);
+        return {
+          ok: true,
+          data: asData({ query, hits }, "docs"),
+        };
+      }
+
+      if (name === "oke.docs.get") {
+        const slug = args.slug;
+        if (typeof slug !== "string" || slug.trim().length === 0) {
+          return {
+            ok: false,
+            code: "invalid",
+            message: "slug must be a non-empty string",
+            data: asData({ reason: "invalid-slug" }, "error"),
+          };
+        }
+        const page = index.get(slug.trim());
+        if (!page) {
+          return {
+            ok: false,
+            code: "not-found",
+            message: `docs page not found: ${slug}`,
+            data: asData({ slug }, "error"),
+          };
+        }
+        return {
+          ok: true,
+          data: asData(
+            {
+              slug: page.slug,
+              path: page.path,
+              title: page.title,
+              url: page.url,
+              body: page.body,
+            },
+            "docs",
+          ),
+        };
+      }
+
+      return {
+        ok: false,
+        code: "not-found",
+        message: `unknown tool: ${name}`,
+        data: asData({ tool: name }, "error"),
+      };
+    },
+  };
+}

package/src/mcp/index.ts

@@ -1,9 +1,7 @@
 /**
- * MCP AI surface on port 6535 (console §10.3 · unified-theory §25).
- *
- * Exposes the Manifest, schemas, effects, traces, and Console-safe runtime
- * actions to agents — read-only by default, write tools gated by fresh
- * human confirmation, every return wrapped as inert data.
+ * MCP AI surfaces (console §10.3 · unified-theory §25):
+ * - App MCP `:6535` — Manifest, schemas, effects, traces, Console-safe actions
+ * - Docs MCP `:6536` — read-only documentation search / fetch
  *
  * Subpath: `okengine/mcp`
  * @module
@@ -79,3 +77,29 @@ export {
   type McpServerHandle,
   type ServeMcpOptions,
 } from "./server.ts";
+
+export {
+  defaultDocsContentDir,
+  loadDocsIndex,
+  parseDocsFrontmatter,
+  stripYamlFrontmatter,
+  type DocsIndex,
+  type DocsPage,
+  type DocsSearchHit,
+} from "./docs-index.ts";
+
+export {
+  createDocsToolRuntime,
+  DOCS_MCP_TOOLS,
+  type DocsToolCallResult,
+  type DocsToolDescriptor,
+} from "./docs-tools.ts";
+
+export {
+  createDocsMcpServer,
+  serveDocsMcp,
+  type CreateDocsMcpServerOptions,
+  type DocsMcpServer,
+  type DocsMcpServerHandle,
+  type ServeDocsMcpOptions,
+} from "./docs-server.ts";

package/src/mcp/protocol.ts

@@ -126,7 +126,8 @@ export interface McpInitializeResult {
     readonly tools: { readonly listChanged: false };
   };
   readonly serverInfo: {
-    readonly name: "okengine-mcp";
+    /** App MCP (`okengine-mcp`) or docs MCP (`okengine-docs-mcp`). */
+    readonly name: "okengine-mcp" | "okengine-docs-mcp";
     readonly version: string;
   };
   /** Cryptographically random transport session id. */

package/src/release/exports.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Published-export discovery for bundle budgets.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { join, resolve } from "node:path";
+import {
+  exportBudgetGroup,
+  exportBudgetLabel,
+  isMeasurableDriverFile,
+  listDriverModules,
+  resolveExportBudgetTargets,
+} from "./exports.ts";
+
+const ROOT = resolve(import.meta.dir, "../..");
+
+describe("export budget targets", () => {
+  test("isMeasurableDriverFile excludes types, tests, barrel, conformance", () => {
+    expect(isMeasurableDriverFile("postgres.ts")).toBe(true);
+    expect(isMeasurableDriverFile("index.ts")).toBe(false);
+    expect(isMeasurableDriverFile("types.ts")).toBe(false);
+    expect(isMeasurableDriverFile("signal-types.ts")).toBe(false);
+    expect(isMeasurableDriverFile("conformance.ts")).toBe(false);
+    expect(isMeasurableDriverFile("conformance.test.ts")).toBe(false);
+    expect(isMeasurableDriverFile("ai-providers.test.ts")).toBe(false);
+  });
+
+  test("exportBudgetLabel / group use short names", () => {
+    expect(exportBudgetLabel(".")).toBe("okengine");
+    expect(exportBudgetLabel("./channel")).toBe("channel");
+    expect(exportBudgetLabel("./drivers/postgres")).toBe("postgres");
+    expect(exportBudgetGroup(".")).toBe("exports");
+    expect(exportBudgetGroup("./channel")).toBe("exports");
+    expect(exportBudgetGroup("./drivers")).toBe("drivers");
+    expect(exportBudgetGroup("./drivers/postgres")).toBe("drivers");
+  });
+
+  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>;
+    };
+    const targets = await resolveExportBudgetTargets();
+    const bySubpath = new Map(targets.map((t) => [t.subpath, t]));
+
+    for (const [subpath, entryRel] of Object.entries(pkg.exports)) {
+      if (subpath.endsWith("/*")) continue;
+      const target = bySubpath.get(subpath);
+      expect(target).toBeDefined();
+      expect(target!.id).toBe(`export:${subpath}`);
+      expect(target!.label).toBe(exportBudgetLabel(subpath));
+      expect(target!.group).toBe(exportBudgetGroup(subpath));
+      expect(target!.entry).toBe(resolve(ROOT, entryRel));
+    }
+
+    const drivers = await listDriverModules();
+    expect(drivers.length).toBeGreaterThan(0);
+    for (const file of drivers) {
+      const name = file.replace(/\.ts$/, "");
+      const subpath = `./drivers/${name}`;
+      const target = bySubpath.get(subpath);
+      expect(target).toBeDefined();
+      expect(target!.id).toBe(`export:${subpath}`);
+      expect(target!.label).toBe(name);
+      expect(target!.group).toBe("drivers");
+      expect(target!.entry).toBe(join(ROOT, "src/drivers", file));
+    }
+
+    // No duplicates.
+    expect(new Set(targets.map((t) => t.id)).size).toBe(targets.length);
+  });
+});

package/src/release/exports.ts

@@ -0,0 +1,156 @@
+/**
+ * Resolve published `package.json` exports into measurable bundle entries.
+ *
+ * Expands `./drivers/*` to concrete driver modules (tree-shaken subpaths).
+ */
+
+import { readdir } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+
+const ROOT = resolve(import.meta.dir, "../..");
+const DRIVERS_DIR = join(ROOT, "src/drivers");
+
+/** Report / snapshot group for a budget sample. */
+export type BudgetGroup = "core" | "exports" | "drivers";
+
+/** One published subpath ready for gzip measurement. */
+export interface ExportBudgetTarget {
+  /** Sample id — `export:<subpath>`. */
+  readonly id: string;
+  /** Package subpath (`.` or `./store`, `./drivers/postgres`, …). */
+  readonly subpath: string;
+  /** Short human label (`channel`, `postgres`, `okengine`, …). */
+  readonly label: string;
+  /** Report section. */
+  readonly group: BudgetGroup;
+  /** Absolute path to the TypeScript entry. */
+  readonly entry: string;
+}
+
+/**
+ * Short display name for a package subpath.
+ *
+ * @param subpath - `.` / `./channel` / `./drivers/postgres`
+ */
+export function exportBudgetLabel(subpath: string): string {
+  if (subpath === ".") return "okengine";
+  if (subpath.startsWith("./drivers/")) {
+    return subpath.slice("./drivers/".length);
+  }
+  if (subpath.startsWith("./")) return subpath.slice(2);
+  return subpath;
+}
+
+/**
+ * Which report section a published export belongs to.
+ *
+ * @param subpath - Package export subpath
+ */
+export function exportBudgetGroup(subpath: string): BudgetGroup {
+  if (subpath === "./drivers" || subpath.startsWith("./drivers/")) {
+    return "drivers";
+  }
+  return "exports";
+}
+
+interface PackageExports {
+  readonly exports?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Whether a driver filename is a measurable protocol module (not types/tests).
+ *
+ * @param name - Basename under `src/drivers/`
+ */
+export function isMeasurableDriverFile(name: string): boolean {
+  if (!name.endsWith(".ts")) return false;
+  if (name === "index.ts") return false;
+  if (name === "conformance.ts") return false;
+  if (name.endsWith(".test.ts")) return false;
+  if (name.endsWith("-types.ts")) return false;
+  if (name === "types.ts") return false;
+  return true;
+}
+
+/**
+ * Discover concrete `okengine/drivers/*` modules under `src/drivers/`.
+ *
+ * @param driversDir - Absolute drivers directory
+ */
+export async function listDriverModules(
+  driversDir = DRIVERS_DIR,
+): Promise<readonly string[]> {
+  const entries = await readdir(driversDir);
+  return entries.filter(isMeasurableDriverFile).sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Resolve every published export into a stable, sorted measurement target list.
+ *
+ * @param options - Override package.json / drivers dir (tests)
+ */
+export async function resolveExportBudgetTargets(options?: {
+  readonly root?: string;
+  readonly pkg?: PackageExports;
+  readonly driversDir?: 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 targets: ExportBudgetTarget[] = [];
+
+  for (const [subpath, entryRel] of Object.entries(exportsMap)) {
+    if (subpath.endsWith("/*")) {
+      if (subpath !== "./drivers/*") {
+        throw new Error(
+          `unsupported export glob ${subpath}: only ./drivers/* is expanded`,
+        );
+      }
+      const modules = await listDriverModules(driversDir);
+      for (const file of modules) {
+        const name = basename(file, ".ts");
+        const driverSubpath = `./drivers/${name}`;
+        targets.push(targetFor(driverSubpath, join(driversDir, file)));
+      }
+      continue;
+    }
+
+    if (typeof entryRel !== "string") {
+      throw new Error(`export ${subpath} must map to a string path`);
+    }
+
+    targets.push(targetFor(subpath, resolve(root, entryRel)));
+  }
+
+  targets.sort((a, b) => {
+    const g = groupOrder(a.group) - groupOrder(b.group);
+    if (g !== 0) return g;
+    // Barrel `drivers` before concrete modules.
+    if (a.subpath === "./drivers") return -1;
+    if (b.subpath === "./drivers") return 1;
+    if (a.subpath === ".") return -1;
+    if (b.subpath === ".") return 1;
+    return a.label.localeCompare(b.label);
+  });
+  return targets;
+}
+
+function targetFor(subpath: string, entry: string): ExportBudgetTarget {
+  return {
+    id: `export:${subpath}`,
+    subpath,
+    label: exportBudgetLabel(subpath),
+    group: exportBudgetGroup(subpath),
+    entry,
+  };
+}
+
+function groupOrder(group: BudgetGroup): number {
+  if (group === "exports") return 0;
+  if (group === "drivers") return 1;
+  return 2;
+}

package/src/release/index.ts

@@ -2,29 +2,50 @@
  * Release engineering — budgets, snapshots, published numbers.
  */
 
+export {
+  exportBudgetGroup,
+  exportBudgetLabel,
+  isMeasurableDriverFile,
+  listDriverModules,
+  resolveExportBudgetTargets,
+  type BudgetGroup,
+  type ExportBudgetTarget,
+} from "./exports.ts";
+
 export {
   CLIENT_BUDGET_BYTES,
   COLD_START_BUDGET_MS,
   CONSOLE_BUDGET_BYTES,
+  EXPORT_REGRESSION_TOLERANCE_FLOOR_BYTES,
+  EXPORT_REGRESSION_TOLERANCE_RATIO,
   KERNEL_EDGE_BUDGET_BYTES,
   ROUTING_P99_BUDGET_MS,
 } from "./limits.ts";
 
 export {
   budgetsPass,
+  exportRegressionLimitBytes,
+  formatBudgetsMarkdown,
   formatBudgetsReport,
+  loadPreviousBudgetValues,
   measureAllBudgets,
   measureClientGzipBytes,
   measureColdStartMedianMs,
   measureConsoleInitialGzipBytes,
+  measureEntryGzipBytes,
+  measureExportGzipBytes,
   measureKernelEdgeGzipBytes,
   measureRoutingP99Ms,
+  type BudgetGate,
   type BudgetSample,
   type BudgetsSnapshot,
 } from "./measure.ts";
 
 export {
   BUDGETS_JSON,
+  BUDGETS_MARKDOWN,
   publishBudgets,
   type PublishBudgetsOptions,
 } from "./publish.ts";
+
+export { BUDGETS_MD } from "./readme.ts";

package/src/release/limits.ts

@@ -18,3 +18,12 @@ export const COLD_START_BUDGET_MS = 75;
 
 /** p99 HTTP routing overhead (match only). */
 export const ROUTING_P99_BUDGET_MS = 1;
+
+/**
+ * Regression tolerance for published-export gzip samples.
+ * Allowed growth = max(floor bytes, ratio × previous).
+ */
+export const EXPORT_REGRESSION_TOLERANCE_RATIO = 0.02;
+
+/** Minimum allowed growth (bytes) before a subpath export fails regression. */
+export const EXPORT_REGRESSION_TOLERANCE_FLOOR_BYTES = 256;

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

@@ -0,0 +1,82 @@
+/**
+ * Export gzip measurement + regression limit helpers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import {
+  exportRegressionLimitBytes,
+  formatBudgetsReport,
+  measureExportGzipBytes,
+  type BudgetsSnapshot,
+} from "./measure.ts";
+import {
+  EXPORT_REGRESSION_TOLERANCE_FLOOR_BYTES,
+  EXPORT_REGRESSION_TOLERANCE_RATIO,
+} from "./limits.ts";
+
+describe("export gzip budgets", () => {
+  test("measureExportGzipBytes(./client) retains the runtime graph", async () => {
+    const entry = resolve(import.meta.dir, "../client/index.ts");
+    const size = await measureExportGzipBytes(entry);
+    // Must not collapse to an empty re-export stub (~100 B).
+    expect(size).toBeGreaterThan(1024);
+  });
+
+  test("exportRegressionLimitBytes uses max(floor, 2% of previous)", () => {
+    expect(exportRegressionLimitBytes(1000)).toBe(
+      1000 + EXPORT_REGRESSION_TOLERANCE_FLOOR_BYTES,
+    );
+    const large = 100_000;
+    expect(exportRegressionLimitBytes(large)).toBe(
+      large + Math.ceil(large * EXPORT_REGRESSION_TOLERANCE_RATIO),
+    );
+  });
+
+  test("formatBudgetsReport groups Core / Exports / Drivers with short names", () => {
+    const snapshot: BudgetsSnapshot = {
+      measuredAt: "2026-07-25T00:00:00.000Z",
+      version: "0.0.0",
+      budgets: [
+        {
+          id: "kernelEdgeGzipBytes",
+          label: "Kernel (edge profile)",
+          value: 100,
+          limit: 200,
+          unit: "bytes",
+          gate: "absolute",
+          group: "core",
+          ok: true,
+        },
+        {
+          id: "export:./channel",
+          label: "channel",
+          value: 100,
+          limit: 200,
+          unit: "bytes",
+          gate: "regression",
+          group: "exports",
+          ok: true,
+        },
+        {
+          id: "export:./drivers/postgres",
+          label: "postgres",
+          value: 100,
+          limit: 200,
+          unit: "bytes",
+          gate: "regression",
+          group: "drivers",
+          ok: true,
+        },
+      ],
+    };
+    const report = formatBudgetsReport(snapshot);
+    expect(report).toContain("\nCore\n");
+    expect(report).toContain("\nExports\n");
+    expect(report).toContain("\nDrivers\n");
+    expect(report).toContain("[ok] channel:");
+    expect(report).toContain("[ok] postgres:");
+    expect(report).not.toContain("regression Export");
+    expect(report).not.toContain("./channel");
+  });
+});