okengine 0.1.6 → 0.2.2

package/docs/spec/unified-theory.md

@@ -416,7 +416,7 @@ Plus `oke import express|hono|elysia` codemods for the mechanical parts. Migrati
 |---|---|
 | Kernel (edge profile) | < 15 kB |
 | Client runtime | < 3 kB |
-| Cold start on Bun | < 75 ms |
+| Cold start on Bun | < 75 ms in CI (GitHub Actions runners are less predictable than a dev machine); measured ~25–30 ms on real hardware |
 | p99 routing overhead | < 1 ms |
 
 A regression fails OKE's own build. Claims we cannot measure, we do not make.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.1.6",
+  "version": "0.2.2",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "type": "module",
@@ -10,7 +10,9 @@
     "url": "git+https://github.com/omqkhafi/okengine.git"
   },
   "workspaces": [
-    "examples/*"
+    "packages/*",
+    "examples/*",
+    "site"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -33,6 +35,7 @@
     "test:mcp": "bun test src/mcp",
     "test:console:smoke": "bunx playwright test tests/console/smoke.spec.ts",
     "build:console": "bunx vite build --config src/console/ui/vite.config.ts",
+    "prepack": "bun run build:console",
     "bench:cold-start": "bun test ./src/runtime/cold-start.bench.ts",
     "bench:client": "bun test src/client/budget.test.ts",
     "bench:console": "bun test src/console/budget.test.ts",
@@ -44,10 +47,13 @@
     "gate:errors": "bun test src/kernel/errors.registry.test.ts",
     "gate:codemods": "bun test src/upgrade/codemods.test.ts",
     "test:examples": "bun test examples/notes && bun test examples/linkly && bun test examples/provisions && bun test examples/skyport",
-    "test:create-oke": "bun run --cwd packages/create-oke typecheck && bun test packages/create-oke/src && CREATE_OKE_INTEGRATION=1 bun test packages/create-oke/tests/scaffold.integration.test.ts packages/create-oke/tests/dev.integration.test.ts",
+    "test:create-oke": "bun run --cwd packages/create-oke typecheck && bun test packages/create-oke/src && CREATE_OKE_INTEGRATION=1 bun test --timeout 180000 packages/create-oke/tests/scaffold.integration.test.ts packages/create-oke/tests/dev.integration.test.ts",
     "test:doc-drift": "bun src/cli/doc-drift.ts",
+    "site:sync": "bun run --cwd site sync",
+    "site:dev": "bun run --cwd site dev",
+    "site:build": "bun run --cwd site build",
     "test:skyport-docker": "bun test examples/skyport/tests/docker.test.ts",
-    "ci": "bun run bench:cold-start && bun run typecheck && bun run test && bun run budgets && bun run gate:doctor-diff && bun run gate:errors && bun run gate:codemods && bun run test:doc-drift && bun run test:examples && bun run test:skyport-docker && bun run test:create-oke",
+    "ci": "bun run bench:cold-start && bun run typecheck && bun run test && bun run budgets && bun run gate:doctor-diff && bun run gate:errors && bun run gate:codemods && bun run test:doc-drift && bun run site:build && bun run test:examples && bun run test:skyport-docker && bun run test:create-oke",
     "gate:publish": "bun test scripts/publish.gate.test.ts",
     "bump": "bun run scripts/bump-version.ts",
     "publish:all": "bun run scripts/publish.ts",
@@ -60,13 +66,13 @@
   },
   "dependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",
-    "age-encryption": "^0.3.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "oxc-parser": "^0.141.0",
     "sently": "^0.8.0"
   },
   "devDependencies": {
+    "age-encryption": "^0.3.0",
     "@base-ui/react": "^1.6.0",
     "@codemirror/commands": "^6.10.4",
     "@codemirror/lang-json": "^6.0.2",
@@ -103,11 +109,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
+    "age-encryption": "^0.3.0",
     "drizzle-kit": ">=1.0.0-rc.0",
     "drizzle-orm": ">=1.0.0-rc.0",
-    "drizzle-seed": ">=0.3.0"
+    "drizzle-seed": ">=0.3.0",
+    "zod": ">=3.23.0"
   },
   "peerDependenciesMeta": {
+    "age-encryption": {
+      "optional": true
+    },
     "drizzle-kit": {
       "optional": true
     },
@@ -116,6 +127,9 @@
     },
     "drizzle-seed": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "engines": {

package/src/cli/dev-app-runner.ts

@@ -17,6 +17,7 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createBunRuntime } from "../runtime/bun.ts";
 import { APP_PORT, type FetchApp } from "../runtime/types.ts";
+import { formatAppReadyLine } from "../term.ts";
 
 /** Stable Bun.serve id so `--hot` reuses the socket across soft reloads. */
 export const DEV_APP_SERVE_ID = "oke-dev-app";
@@ -59,8 +60,11 @@ const handle = createBunRuntime().serve(mod.app, {
   id: DEV_APP_SERVE_ID,
 });
 
-const line = `oke app http://${formatHostForUrl(hostname)}:${handle.port}\n`;
-process.stdout.write(line);
+process.stdout.write(
+  formatAppReadyLine(
+    `http://${formatHostForUrl(hostname)}:${handle.port}`,
+  ),
+);
 
 if (readyPath !== undefined && readyPath.length > 0) {
   await Bun.write(readyPath, `${handle.port}\n`);

package/src/cli/dev.ts

@@ -23,6 +23,11 @@ import {
   CONSOLE_PORT,
   MCP_PORT,
 } from "../runtime/types.ts";
+import {
+  formatDevBanner,
+  formatServiceLine,
+  formatStatusLine,
+} from "../term.ts";
 import { clientAdd } from "./client-add.ts";
 import { loadManifest, loadOkeConfig, resolveImages } from "./load-config.ts";
 import { mcpContextFromConsole } from "./mcp-from-console.ts";
@@ -258,7 +263,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           }
         });
       await up(composeFiles, cwd);
-      write(`oke dev: stack up (${stackRoles.join(", ")})\n`);
+      write(formatStatusLine(`stack up (${stackRoles.join(", ")})`));
     }
   }
 
@@ -272,10 +277,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stackEnv,
   };
 
-  write(
-    `oke dev: app :${appPort} · Console :${consolePort} · MCP :${mcpPort}\n`,
-  );
-  write("oke dev: watching — client types regenerate on save\n");
+  write(formatDevBanner());
 
   if (options.dryRun) return { code: 0, plan };
 
@@ -312,7 +314,12 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           ? { manifest: seedManifest }
           : {}),
       });
-      write(`oke Console http://127.0.0.1:${server.port}\n`);
+      write(
+        formatServiceLine(
+          "Console",
+          `http://127.0.0.1:${server.port}`,
+        ),
+      );
       return {
         console: server.console,
         port: server.port,
@@ -334,7 +341,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
         context: mcpOptions.context,
         now: mcpOptions.now,
       });
-      write(`oke MCP http://127.0.0.1:${server.port}\n`);
+      write(formatServiceLine("MCP", `http://127.0.0.1:${server.port}`));
       return {
         port: server.port,
         url: server.url,
@@ -352,7 +359,7 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
           url: appUrl,
           out: resolve(cwd, "oke-client.d.ts"),
         });
-        write("oke dev: regenerated oke-client.d.ts\n");
+        write(formatStatusLine("regenerated oke-client.d.ts"));
       } catch {
         // App may not be ready yet — ignore until next save.
       }
@@ -500,7 +507,9 @@ async function startAppHot(
     if (stopped) return;
     stopped = true;
     try {
-      proc.kill();
+      // SIGKILL so `bun --hot` cannot linger and hold the project directory
+      // open (create-oke afterEach `rmSync` otherwise races the child exit).
+      proc.kill("SIGKILL");
     } catch {
       // already exited
     }
@@ -513,7 +522,7 @@ async function startAppHot(
       proc,
       APP_READY_TIMEOUT_MS,
     );
-    // Child prints `oke app http://…` (again on each soft reload).
+    // Child prints the App ready line (again on each soft reload).
     const url = new URL(`http://${hostname}:${boundPort}/`);
     return { stop, port: boundPort, url };
   } catch (err) {

package/src/cli/doc-drift.ts

@@ -14,6 +14,10 @@
  * Usage:
  *   bun src/cli/doc-drift.ts
  *   bun src/cli/doc-drift.ts docs/spec/four-applications.md README.md
+ *   bun src/cli/doc-drift.ts site/content/docs/learn/notes.md
+ *
+ * Default paths: four-applications.md, README.md, and every markdown/MDX file
+ * under site/content/docs (claimed fences only — prose-only pages skip).
  */
 
 import { resolve } from "node:path";
@@ -21,8 +25,27 @@ import { Window } from "happy-dom";
 
 const ROOT = resolve(import.meta.dir, "../..");
 
-/** Default docs checked when no CLI paths are passed. */
-const DEFAULT_DOCS: readonly string[] = [
+/**
+ * Discover site content markdown that may contain claimed fences.
+ *
+ * @param root - Repo root
+ */
+async function discoverSiteDocs(root: string): Promise<string[]> {
+  const docsDir = resolve(root, "site/content/docs");
+  const out: string[] = [];
+  try {
+    const glob = new Bun.Glob("**/*.{md,mdx}");
+    for await (const rel of glob.scan({ cwd: docsDir, onlyFiles: true })) {
+      out.push(resolve(docsDir, rel));
+    }
+  } catch {
+    // site/ not present yet — skip
+  }
+  return out.sort();
+}
+
+/** Core docs that must contain claimed fences. */
+const REQUIRED_DOCS: readonly string[] = [
   resolve(ROOT, "docs/spec/four-applications.md"),
   resolve(ROOT, "README.md"),
 ];
@@ -315,6 +338,9 @@ export async function checkDocDrift(
 /**
  * Run doc-drift over one or more markdown files.
  *
+ * Site content under `site/` may have zero claimed fences (prose-only pages);
+ * only `docs/spec/four-applications.md` and `README.md` require at least one.
+ *
  * @param paths - Absolute or repo-relative markdown paths
  */
 export async function runDocDrift(
@@ -324,32 +350,36 @@ export async function runDocDrift(
   let ok = true;
   let total = 0;
   let mermaidTotal = 0;
+  let checkedFiles = 0;
 
   for (const path of paths) {
     const abs = resolve(ROOT, path);
     const label = abs.startsWith(ROOT + "/")
       ? abs.slice(ROOT.length + 1)
       : abs;
+    const requireClaimed = !label.startsWith("site/");
     const markdown = await Bun.file(abs).text();
     const fences = parseClaimedFences(markdown);
     if (fences.length === 0) {
-      messages.push(`doc-drift: no claimed fences found in ${label}`);
-      ok = false;
-      continue;
-    }
-
-    const result = await checkDocDrift(fences);
-    total += fences.length;
-    if (!result.ok) {
-      ok = false;
-      messages.push(
-        `doc-drift: ${result.failures.length} failure(s) in ${label}`,
-      );
-      for (const f of result.failures) messages.push(`  · ${f}`);
+      if (requireClaimed) {
+        messages.push(`doc-drift: no claimed fences found in ${label}`);
+        ok = false;
+      }
     } else {
-      messages.push(
-        `doc-drift: ok — ${fences.length} claimed fence(s) in ${label}`,
-      );
+      checkedFiles++;
+      const result = await checkDocDrift(fences);
+      total += fences.length;
+      if (!result.ok) {
+        ok = false;
+        messages.push(
+          `doc-drift: ${result.failures.length} failure(s) in ${label}`,
+        );
+        for (const f of result.failures) messages.push(`  · ${f}`);
+      } else {
+        messages.push(
+          `doc-drift: ok — ${fences.length} claimed fence(s) in ${label}`,
+        );
+      }
     }
 
     const mermaidFences = parseMermaidFences(markdown);
@@ -370,11 +400,11 @@ export async function runDocDrift(
     }
   }
 
-  if (ok && paths.length > 1) {
+  if (ok && checkedFiles > 1) {
     const mermaidNote =
       mermaidTotal > 0 ? ` · ${mermaidTotal} mermaid fence(s)` : "";
     messages.push(
-      `doc-drift: ok — ${total} claimed fence(s) across ${paths.length} file(s)${mermaidNote}`,
+      `doc-drift: ok — ${total} claimed fence(s) across ${checkedFiles} file(s)${mermaidNote}`,
     );
   }
 
@@ -383,7 +413,10 @@ export async function runDocDrift(
 
 async function main(): Promise<number> {
   const args = process.argv.slice(2);
-  const paths = args.length > 0 ? args : DEFAULT_DOCS;
+  const paths =
+    args.length > 0
+      ? args
+      : [...REQUIRED_DOCS, ...(await discoverSiteDocs(ROOT))];
   const { ok, messages } = await runDocDrift(paths);
   for (const m of messages) {
     if (ok) console.log(m);

package/src/console/index.ts

@@ -3,29 +3,41 @@
  *
  * Built on `createClient<ConsoleApp>`. Every action is a real flow through `fx`;
  * the audit log is the trace (docs/spec/console.md).
+ *
+ * Imports leaf modules (not `server/index`) so unused panel projectors stay out
+ * of the `okengine/console` graph when tree-shaken.
+ *
  * @module
  */
 
 export {
   bootConsoleApp,
+  createConsoleApp,
+  type ConsoleApp,
+  type ConsoleAppHandle,
+  type CreateConsoleAppOptions,
+} from "./server/app.ts";
+export {
   CLAIM_TTL_MS,
+  mintClaimCode,
+  printClaimCodeOnce,
+  verifyClaimCode,
+} from "./server/claim.ts";
+export { feedManifest } from "./server/live.ts";
+export { consolePlugin } from "./server/plugin.ts";
+export {
   CONSOLE_COOKIES,
   CONSOLE_CSP,
   PLUGIN_IFRAME_SANDBOX,
-  consolePlugin,
-  createConsoleApp,
-  createConsoleState,
-  feedManifest,
-  mintClaimCode,
-  printClaimCodeOnce,
+  withConsoleSecurityHeaders,
+} from "./server/security-headers.ts";
+export {
   serveConsole,
   startConsoleApp,
-  verifyClaimCode,
-  withConsoleSecurityHeaders,
-  type ConsoleApp,
-  type ConsoleAppHandle,
   type ConsoleServerHandle,
-  type ConsoleState,
-  type CreateConsoleAppOptions,
   type ServeConsoleOptions,
-} from "./server/index.ts";
+} from "./server/serve.ts";
+export {
+  createConsoleState,
+  type ConsoleState,
+} from "./server/state.ts";

package/src/console/server/app.ts

@@ -140,16 +140,53 @@ export async function bootConsoleApp(
     if (!runs) return [];
     return runs.all();
   };
-  await bindManifestSignalBus(handle.state);
-  await bindManifestStoreRuntime(handle.state);
-  await bindManifestVaultRuntime(handle.state);
-  await bindManifestGateRuntime(handle.state);
-  await bindManifestClockRuntime(handle.state);
-  bindManifestAiRuntime(handle.state);
-  bindManifestChannelRuntime(handle.state);
+  // Element runtimes bind lazily on first panel access (see ensure* below
+  // via list* methods / bindManifest* callers) — not all seventeen at boot.
   return handle.app;
 }
 
+/**
+ * Ensure Manifest-backed element runtimes for a panel are bound (idempotent).
+ *
+ * @param state - Console state
+ * @param panel - Panel id that was visited
+ */
+export async function ensureConsolePanelRuntimes(
+  state: ConsoleState,
+  panel:
+    | "signals"
+    | "store"
+    | "vault"
+    | "gates"
+    | "clock"
+    | "ai"
+    | "channels",
+): Promise<void> {
+  switch (panel) {
+    case "signals":
+      await bindManifestSignalBus(state);
+      break;
+    case "store":
+      await bindManifestStoreRuntime(state);
+      break;
+    case "vault":
+      await bindManifestVaultRuntime(state);
+      break;
+    case "gates":
+      await bindManifestGateRuntime(state);
+      break;
+    case "clock":
+      await bindManifestClockRuntime(state);
+      break;
+    case "ai":
+      bindManifestAiRuntime(state);
+      break;
+    case "channels":
+      bindManifestChannelRuntime(state);
+      break;
+  }
+}
+
 /**
  * Bind a ChannelRuntime + console inbox from the Manifest when no host
  * runtime is attached — Console surfaces real receipts / inbox, not mocks.

package/src/console/server/claim.test.ts

@@ -52,10 +52,13 @@ describe("claim code", () => {
 
   test("prints to boot log exactly once", () => {
     const state = mintClaimCode(() => 1);
-    const lines: string[] = [];
-    printClaimCodeOnce(state, (l) => lines.push(l));
-    printClaimCodeOnce(state, (l) => lines.push(l));
-    expect(lines.filter((l) => l.includes(state.code)).length).toBe(1);
+    const chunks: string[] = [];
+    printClaimCodeOnce(state, (l) => chunks.push(l));
+    printClaimCodeOnce(state, (l) => chunks.push(l));
+    const joined = chunks.join("");
+    expect(joined).toContain(state.code);
+    expect(joined).toContain("Claim code");
+    expect(chunks.length).toBe(1);
   });
 
   test("constantTimeEqual is length-safe", () => {

package/src/console/server/claim.ts

@@ -5,6 +5,7 @@
  * and rate-limited (console §2.5 · §10.4).
  */
 
+import { formatClaimNote } from "../../term.ts";
 import {
   AUTH_RATE_LIMIT,
   AUTH_RATE_WINDOW_MS,
@@ -67,13 +68,7 @@ export function printClaimCodeOnce(
 ): void {
   if (state.printed) return;
   state.printed = true;
-  write("");
-  write("┌─────────────────────────────────────────────────────────┐");
-  write("│  oke Console — first-admin claim code (expires 30 min)  │");
-  write(`│  ${state.code}  │`);
-  write("│  Whoever can read this log already owns the server.     │");
-  write("└─────────────────────────────────────────────────────────┘");
-  write("");
+  write(formatClaimNote(state.code));
 }
 
 /** Result of {@link verifyClaimCode}. */

package/src/console/server/flows.ts

@@ -30,14 +30,10 @@ import {
 } from "./clock.ts";
 import { createFileDiff, emitStructuralDiff } from "./structural.ts";
 import type { ConsoleState } from "./state.ts";
+import { PUBLIC_CONSOLE_FLOWS } from "./public-flows.ts";
 import { tenancyDeclared } from "./store.ts";
 
-/** Flows that may run without an operator session. */
-export const PUBLIC_CONSOLE_FLOWS = new Set([
-  "console.setup.status",
-  "console.setup.claim",
-  "console.session.login",
-]);
+export { PUBLIC_CONSOLE_FLOWS };
 
 const SetupStatusOut = z.object({
   setupClosed: z.boolean(),

package/src/console/server/index.ts

@@ -30,6 +30,7 @@ export {
   bindManifestVaultRuntime,
   bootConsoleApp,
   createConsoleApp,
+  ensureConsolePanelRuntimes,
   type ConsoleApp,
   type ConsoleAppHandle,
   type CreateConsoleAppOptions,
@@ -72,8 +73,8 @@ export {
 } from "./claim.ts";
 export {
   createConsoleBindings,
-  PUBLIC_CONSOLE_FLOWS,
 } from "./flows.ts";
+export { PUBLIC_CONSOLE_FLOWS } from "./public-flows.ts";
 export {
   createLiveWebsocket,
   feedManifest,

package/src/console/server/lazy-panels.test.ts

@@ -0,0 +1,27 @@
+/**
+ * Console per-panel backends construct lazily on first access.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createConsoleState } from "./state.ts";
+
+describe("console — lazy panel construction", () => {
+  test("createConsoleState constructs no panel backends", () => {
+    const state = createConsoleState({ silentClaim: true, secret: "x" });
+    expect([...state.constructedPanels]).toEqual([]);
+  });
+
+  test("only the visited panel is constructed", async () => {
+    const state = createConsoleState({ silentClaim: true, secret: "x" });
+    expect([...state.constructedPanels]).toEqual([]);
+
+    await state.listVault();
+    expect([...state.constructedPanels]).toEqual(["vault"]);
+
+    await state.listStores();
+    expect([...state.constructedPanels].sort()).toEqual(["store", "vault"]);
+
+    await state.listVault();
+    expect([...state.constructedPanels].sort()).toEqual(["store", "vault"]);
+  });
+});

package/src/console/server/panel-load.ts

@@ -0,0 +1,28 @@
+/**
+ * Lazy Console panel module loader — expression `new URL` keeps panel
+ * backends out of the createConsoleState / createConsoleApp graph until
+ * first access (mirrors kernel boot-bind).
+ */
+
+/** Panel ids that own server-side projection / mutation modules. */
+export type ConsolePanelId =
+  | "access"
+  | "gates"
+  | "signals"
+  | "store"
+  | "clock"
+  | "vault"
+  | "ai"
+  | "channels"
+  | "plugins"
+  | "diff";
+
+/**
+ * Load a Console panel module by id without bundling it into the parent.
+ *
+ * @param id - Panel module stem (`store`, `vault`, …)
+ */
+export async function loadConsolePanel<T>(id: ConsolePanelId): Promise<T> {
+  const url = new URL(`./${id}.ts`, import.meta.url);
+  return import(url.href) as Promise<T>;
+}

package/src/console/server/plugin.ts

@@ -10,7 +10,7 @@ import {
   type Fx,
   type PluginDef,
 } from "../../kernel/index.ts";
-import { PUBLIC_CONSOLE_FLOWS } from "./flows.ts";
+import { PUBLIC_CONSOLE_FLOWS } from "./public-flows.ts";
 
 /**
  * Builtin Console plugin.

package/src/console/server/plugins.ts

@@ -6,7 +6,6 @@
  * Never installs — hands a `bun add …` command for community packages.
  */
 
-import { runDoctorDiff } from "../../cli/doctor-diff.ts";
 import {
   allHookCostSummaries,
   type HookCostSummary,
@@ -23,11 +22,9 @@ import {
   isCorePluginOn,
   type PluginConfigProbe,
 } from "../../plugins/catalogue.ts";
-import {
-  projectSupplyChain,
-  projectSupplyChainSync,
-  type PackageJsonProbe,
-  type SupplyChainSignals,
+import type {
+  PackageJsonProbe,
+  SupplyChainSignals,
 } from "../../plugins/supply-chain.ts";
 import type { ScanSourceFile } from "../../plugins/node-import-scan.ts";
 
@@ -308,6 +305,9 @@ async function buildRow(input: {
     fetchNpm: input.options.fetchNpm,
   };
 
+  const { projectSupplyChain, projectSupplyChainSync } = await import(
+    "../../plugins/supply-chain.ts"
+  );
   const supplyChain = input.options.syncSupplyChain
     ? projectSupplyChainSync(supplyOpts)
     : await projectSupplyChain(supplyOpts);
@@ -357,6 +357,7 @@ export async function loadCapabilityDiffByPlugin(
   manifest: Manifest | null,
 ): Promise<Readonly<Record<string, readonly ManifestChange[]>>> {
   try {
+    const { runDoctorDiff } = await import("../../cli/doctor-diff.ts");
     const result = await runDoctorDiff({
       cwd,
       ...(manifest ? { after: manifest } : {}),

package/src/console/server/public-flows.ts

@@ -0,0 +1,12 @@
+/**
+ * Console flows that may run without an operator session.
+ *
+ * Kept out of `flows.ts` so `consolePlugin` does not pull the full flow graph.
+ */
+
+/** Public setup / session entry flows (no operator session required). */
+export const PUBLIC_CONSOLE_FLOWS = new Set([
+  "console.setup.status",
+  "console.setup.claim",
+  "console.session.login",
+]);