okengine 0.1.4

package/src/cli/schema.ts

@@ -0,0 +1,196 @@
+/**
+ * `oke schema generate` — core + plugin tables → `schema/oke.ts`.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import type { Manifest } from "../manifest/types.ts";
+import { loadManifest } from "./load-config.ts";
+
+/** Fingerprint file written beside generated schema. */
+export const SCHEMA_FINGERPRINT_FILE = "schema/.oke-schema.sha256";
+
+/** Default generated schema path. */
+export const SCHEMA_OUT = "schema/oke.ts";
+
+/** Options for {@link runSchemaGenerate}. */
+export interface SchemaGenerateOptions {
+  readonly cwd?: string;
+  readonly manifestPath?: string;
+  readonly manifest?: Manifest;
+  readonly out?: string;
+  /** When true, fail if output would change (CI). */
+  readonly check?: boolean;
+  readonly write?: (text: string) => void;
+  /** Extra table names (plugins / tests). */
+  readonly extraTables?: readonly string[];
+}
+
+/**
+ * Generate `schema/oke.ts` from Manifest store tables + core Console tables.
+ *
+ * @param options - Manifest / check flag
+ */
+export async function runSchemaGenerate(
+  options: SchemaGenerateOptions = {},
+): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const cwd = options.cwd ?? process.cwd();
+  let manifest = options.manifest;
+  if (!manifest) {
+    const path = resolve(cwd, options.manifestPath ?? "oke.manifest.json");
+    const file = Bun.file(path);
+    if (await file.exists()) manifest = await loadManifest(path);
+  }
+
+  const tables = new Set<string>([
+    "oke_roles",
+    "oke_role_grants",
+    "oke_api_keys",
+    "oke_overrides",
+    "oke_crons",
+    "oke_signal_config",
+    "oke_console_prefs",
+    ...(options.extraTables ?? []),
+  ]);
+  if (manifest?.stores) {
+    for (const store of Object.values(manifest.stores)) {
+      for (const t of Object.keys(store.tables ?? {})) tables.add(t);
+    }
+  }
+
+  const source = emitSchemaSource([...tables].sort());
+  const out = resolve(cwd, options.out ?? SCHEMA_OUT);
+  const fp = hashSource(source);
+
+  if (options.check) {
+    const existing = Bun.file(out);
+    if (!(await existing.exists())) {
+      write("oke schema generate --check: schema/oke.ts missing\n");
+      return 1;
+    }
+    const current = await existing.text();
+    if (hashSource(current) !== fp) {
+      write("oke schema generate --check: schema drift\n");
+      return 1;
+    }
+    write("oke schema generate --check: ok\n");
+    return 0;
+  }
+
+  await mkdir(dirname(out), { recursive: true });
+  await Bun.write(out, source);
+  await Bun.write(resolve(cwd, SCHEMA_FINGERPRINT_FILE), `${fp}\n`);
+  write(`oke schema generate: wrote ${out} (${tables.size} table(s))\n`);
+  return 0;
+}
+
+/**
+ * Fingerprint of the would-be generated schema (for doctor drift).
+ *
+ * @param cwd - Project root
+ * @param manifest - Optional manifest
+ */
+export async function schemaFingerprint(
+  cwd: string,
+  manifest?: Manifest,
+): Promise<string> {
+  const tables = new Set<string>([
+    "oke_roles",
+    "oke_role_grants",
+    "oke_api_keys",
+    "oke_overrides",
+    "oke_crons",
+    "oke_signal_config",
+    "oke_console_prefs",
+  ]);
+  let m = manifest;
+  if (!m) {
+    const path = resolve(cwd, "oke.manifest.json");
+    if (await Bun.file(path).exists()) m = await loadManifest(path);
+  }
+  if (m?.stores) {
+    for (const store of Object.values(m.stores)) {
+      for (const t of Object.keys(store.tables ?? {})) tables.add(t);
+    }
+  }
+  return hashSource(emitSchemaSource([...tables].sort()));
+}
+
+/**
+ * Read the on-disk schema fingerprint, if any.
+ *
+ * @param cwd - Project root
+ */
+export async function readSchemaFingerprint(
+  cwd: string,
+): Promise<string | null> {
+  const fpFile = Bun.file(resolve(cwd, SCHEMA_FINGERPRINT_FILE));
+  if (await fpFile.exists()) {
+    return (await fpFile.text()).trim();
+  }
+  const schema = Bun.file(resolve(cwd, SCHEMA_OUT));
+  if (!(await schema.exists())) return null;
+  return hashSource(await schema.text());
+}
+
+/**
+ * CLI entry for `oke schema generate [--check]`.
+ *
+ * @param args - Args after `schema`
+ */
+export async function schemaCli(args: readonly string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  if (sub !== "generate") {
+    console.error("Usage: oke schema generate [--check|-c]");
+    return 1;
+  }
+  let check = false;
+  let manifestPath: string | undefined;
+  let out: string | undefined;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (a === "--check" || a === "-c") check = true;
+    else if (a === "--manifest" || a === "-m") manifestPath = rest[++i];
+    else if (a === "--out" || a === "-o") out = rest[++i];
+    else if (a === "--help" || a === "-h") {
+      console.log(`oke schema generate [--check|-c] [--out|-o schema/oke.ts]
+
+Emit core + plugin tables. Use --check in CI to fail on drift.
+`);
+      return 0;
+    }
+  }
+  return runSchemaGenerate({ check, manifestPath, out });
+}
+
+/**
+ * Emit a Drizzle-compatible stub schema module.
+ *
+ * @param tables - Table names
+ */
+export function emitSchemaSource(tables: readonly string[]): string {
+  const decls = tables
+    .map(
+      (name) =>
+        `/** Generated table handle — wire columns in your app schema. */\nexport const ${camel(name)} = { name: "${name}" } as const;\n`,
+    )
+    .join("\n");
+  return `/**
+ * Generated by \`oke schema generate\` — do not edit.
+ * Core Console tables + Manifest store tables.
+ */
+
+${decls}
+export const okeTables = [${tables.map((t) => `"${t}"`).join(", ")}] as const;
+`;
+}
+
+function hashSource(source: string): string {
+  return createHash("sha256").update(source).digest("hex");
+}
+
+function camel(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}

package/src/cli/stack.ts

@@ -0,0 +1,82 @@
+/**
+ * `oke stack` — preview resolved images/tags/ports (writes nothing).
+ */
+
+import { formatStackPreview, resolveStack } from "../docker/index.ts";
+import { wantsJson } from "./args.ts";
+import { EXIT_OK, EXIT_RUNTIME } from "./exit.ts";
+import { loadOkeConfig, resolveImages } from "./load-config.ts";
+
+/** Options for {@link runStackPreview}. */
+export interface StackCliOptions {
+  readonly cwd?: string;
+  readonly configPath?: string;
+  readonly images?: Readonly<Record<string, string>>;
+  readonly write?: (text: string) => void;
+  readonly writeErr?: (text: string) => void;
+  readonly json?: boolean;
+}
+
+/**
+ * Print resolved stack preview.
+ *
+ * @param options - Config / images
+ */
+export async function runStackPreview(
+  options: StackCliOptions = {},
+): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const writeErr = options.writeErr ?? ((t) => process.stderr.write(t));
+  const json = options.json ?? false;
+  let images = options.images;
+  if (!images) {
+    try {
+      const loaded = await loadOkeConfig(
+        options.cwd ?? process.cwd(),
+        options.configPath,
+      );
+      images = resolveImages(loaded.config);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (json) {
+        write(`${JSON.stringify({ ok: false, error: msg }, null, 2)}\n`);
+      } else {
+        writeErr(`${msg}\n`);
+      }
+      return EXIT_RUNTIME;
+    }
+  }
+  const rows = resolveStack({ images });
+  if (json) {
+    write(`${JSON.stringify({ ok: true, rows }, null, 2)}\n`);
+    if (rows.length === 0) {
+      writeErr("Hint: set images in oke.config.ts — oke stack writes nothing.\n");
+    }
+    return EXIT_OK;
+  }
+  write(formatStackPreview(rows));
+  return EXIT_OK;
+}
+
+/**
+ * CLI entry for `oke stack`.
+ *
+ * @param args - Args after `stack`
+ */
+export async function stackCli(args: readonly string[]): Promise<number> {
+  let configPath: string | undefined;
+  const json = wantsJson(args);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--config" || a === "-c") configPath = args[++i];
+    else if (a === "--help" || a === "-h") {
+      console.log(`oke stack [--config|-c oke.config.ts] [--json|-j]
+
+Preview resolved images, recipes, and ports. Writes nothing.
+--json  Machine-parseable JSON on stdout; hints on stderr.
+`);
+      return EXIT_OK;
+    }
+  }
+  return runStackPreview({ configPath, json });
+}

package/src/cli/start.ts

@@ -0,0 +1,106 @@
+/**
+ * `oke start` — runs exactly what production runs (Docker CMD).
+ */
+
+import { resolve } from "node:path";
+import { APP_PORT } from "../runtime/types.ts";
+
+/** Options for {@link runStart}. */
+export interface StartOptions {
+  readonly cwd?: string;
+  readonly entry?: string;
+  readonly port?: number;
+  readonly write?: (text: string) => void;
+  /**
+   * Spawn/import hook (tests). Defaults to dynamic-importing the entry.
+   *
+   * @param entry - Absolute entry path
+   * @param env - Process env overlay
+   */
+  readonly runEntry?: (
+    entry: string,
+    env: Record<string, string>,
+  ) => Promise<void>;
+}
+
+/**
+ * Resolve the production entry module.
+ *
+ * @param cwd - Project root
+ * @param explicit - Optional `--entry`
+ */
+export async function resolveStartEntry(
+  cwd: string,
+  explicit?: string,
+): Promise<string> {
+  if (explicit) return resolve(cwd, explicit);
+  const pkgPath = resolve(cwd, "package.json");
+  if (await Bun.file(pkgPath).exists()) {
+    const pkg = (await Bun.file(pkgPath).json()) as {
+      main?: string;
+      okengine?: { entry?: string };
+    };
+    if (pkg.okengine?.entry) return resolve(cwd, pkg.okengine.entry);
+    if (pkg.main) return resolve(cwd, pkg.main);
+  }
+  for (const candidate of ["src/app.ts", "src/index.ts", "index.ts", "app.ts"]) {
+    const path = resolve(cwd, candidate);
+    if (await Bun.file(path).exists()) return path;
+  }
+  throw new Error(
+    "oke start: no entry found — set package.json okengine.entry or pass --entry",
+  );
+}
+
+/**
+ * Run the production entry (Docker CMD).
+ *
+ * @param options - Entry / port
+ */
+export async function runStart(options: StartOptions = {}): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const cwd = options.cwd ?? process.cwd();
+  try {
+    const entry = await resolveStartEntry(cwd, options.entry);
+    const port = String(options.port ?? Number(Bun.env.PORT ?? APP_PORT));
+    const env = { ...process.env, NODE_ENV: "production", PORT: port } as Record<
+      string,
+      string
+    >;
+    write(`oke start: ${entry} (port ${port})\n`);
+    if (options.runEntry) {
+      await options.runEntry(entry, env);
+      return 0;
+    }
+    // Production: import the entry; apps call createBunRuntime().serve themselves.
+    Object.assign(process.env, env);
+    await import(entry);
+    return 0;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+
+/**
+ * CLI entry for `oke start`.
+ *
+ * @param args - Args after `start`
+ */
+export async function startCli(args: readonly string[]): Promise<number> {
+  let entry: string | undefined;
+  let port: number | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--entry" || a === "-e") entry = args[++i];
+    else if (a === "--port" || a === "-p") port = Number(args[++i]);
+    else if (a === "--help" || a === "-h") {
+      console.log(`oke start [--entry|-e src/app.ts] [--port|-p 6530]
+
+Run exactly what production runs. This is the Docker CMD.
+`);
+      return 0;
+    }
+  }
+  return runStart({ entry, port });
+}

package/src/cli/upgrade.ts

@@ -0,0 +1,105 @@
+/**
+ * `oke upgrade` — run codemods for a breaking change, print the diff.
+ */
+
+import {
+  runCodemods,
+  type CodemodChange,
+} from "../upgrade/codemods.ts";
+
+/** One file rewrite produced by a codemod. */
+export type UpgradeChange = CodemodChange;
+
+/** Options for {@link runUpgrade}. */
+export interface UpgradeOptions {
+  readonly cwd?: string;
+  readonly write?: (text: string) => void;
+  /** Apply without writing (print diff only). Default true for safety. */
+  readonly dryRun?: boolean;
+  /**
+   * Codemod runner (tests / versioned transforms).
+   *
+   * @param cwd - Project root
+   */
+  readonly runCodemods?: (cwd: string) => Promise<readonly UpgradeChange[]>;
+}
+
+/**
+ * Run upgrade codemods and print a unified-style diff.
+ *
+ * @param options - Cwd / dry-run
+ */
+export async function runUpgrade(options: UpgradeOptions = {}): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const cwd = options.cwd ?? process.cwd();
+  const dryRun = options.dryRun ?? true;
+  const run = options.runCodemods ?? runCodemods;
+
+  try {
+    const changes = await run(cwd);
+    if (changes.length === 0) {
+      write("oke upgrade: no codemods to apply\n");
+      return 0;
+    }
+    for (const c of changes) {
+      write(`--- a/${c.path}\n+++ b/${c.path}\n`);
+      write(unifiedDiff(c.before, c.after));
+      if (!dryRun) await Bun.write(`${cwd}/${c.path}`, c.after);
+    }
+    write(
+      dryRun
+        ? `oke upgrade: ${changes.length} change(s) (dry-run — pass --apply to write)\n`
+        : `oke upgrade: applied ${changes.length} change(s)\n`,
+    );
+    return 0;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+}
+
+/**
+ * CLI entry for `oke upgrade`.
+ *
+ * @param args - Args after `upgrade`
+ */
+export async function upgradeCli(args: readonly string[]): Promise<number> {
+  let dryRun = true;
+  for (const a of args) {
+    if (a === "--apply" || a === "-a") dryRun = false;
+    else if (a === "--help" || a === "-h") {
+      console.log(`oke upgrade [--apply|-a]
+
+Run codemods for a breaking change and print the diff.
+Pass --apply to write files (default is dry-run — never writes without it).
+Codemods ship with every breaking change (unified-theory §22).
+`);
+      return 0;
+    }
+  }
+  return runUpgrade({ dryRun });
+}
+
+/**
+ * Minimal unified diff for short files.
+ *
+ * @param before - Original
+ * @param after - Rewritten
+ */
+export function unifiedDiff(before: string, after: string): string {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  const lines: string[] = [];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i++) {
+    const left = a[i];
+    const right = b[i];
+    if (left === right) {
+      if (left !== undefined) lines.push(` ${left}`);
+    } else {
+      if (left !== undefined) lines.push(`-${left}`);
+      if (right !== undefined) lines.push(`+${right}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/cli/vault-cmd.ts

@@ -0,0 +1,140 @@
+/**
+ * `oke vault` — set · list · import · key rotate.
+ */
+
+import { resolve } from "node:path";
+import { parseDotenv, formatDotenv } from "../drivers/vault-dotenv-parse.ts";
+
+/** In-memory / file-backed vault bag for CLI (dotenv-shaped). */
+export interface VaultCliStore {
+  get(name: string): string | undefined;
+  set(name: string, value: string): void;
+  names(): readonly string[];
+  save?(): Promise<void>;
+}
+
+/** Options shared by vault subcommands. */
+export interface VaultCmdOptions {
+  readonly cwd?: string;
+  readonly envFile?: string;
+  readonly store?: VaultCliStore;
+  readonly write?: (text: string) => void;
+  readonly readLine?: (prompt: string) => Promise<string>;
+}
+
+/**
+ * Open a dotenv-backed store (default `.env.local`).
+ *
+ * @param path - Env file path
+ */
+export async function openEnvStore(path: string): Promise<VaultCliStore> {
+  const map = new Map<string, string>();
+  const file = Bun.file(path);
+  if (await file.exists()) {
+    for (const [k, v] of parseDotenv(await file.text())) {
+      map.set(k, v);
+    }
+  }
+  return {
+    get: (n) => map.get(n),
+    set: (n, v) => {
+      map.set(n, v);
+    },
+    names: () => [...map.keys()].sort(),
+    async save() {
+      await Bun.write(path, formatDotenv(map));
+    },
+  };
+}
+
+/**
+ * Run a vault subcommand.
+ *
+ * @param args - Args after `vault`
+ * @param options - Store injection
+ */
+export async function vaultCli(
+  args: readonly string[],
+  options: VaultCmdOptions = {},
+): Promise<number> {
+  const write = options.write ?? ((t) => process.stdout.write(t));
+  const [sub, ...rest] = args;
+  if (!sub || sub === "--help" || sub === "-h") {
+    write(`oke vault set <NAME> [value]
+oke vault list
+oke vault import <file>
+oke vault key rotate
+`);
+    return sub ? 0 : 1;
+  }
+
+  const cwd = options.cwd ?? process.cwd();
+  const envFile = resolve(cwd, options.envFile ?? ".env.local");
+  const store = options.store ?? (await openEnvStore(envFile));
+
+  if (sub === "set") {
+    const name = rest[0];
+    if (!name) {
+      console.error("Usage: oke vault set <NAME> [value]");
+      return 1;
+    }
+    let value = rest[1];
+    if (value === undefined) {
+      const read =
+        options.readLine ??
+        (async () => {
+          write(`Enter value for ${name}: `);
+          const chunks: Buffer[] = [];
+          for await (const chunk of Bun.stdin.stream()) {
+            chunks.push(Buffer.from(chunk));
+            if (Buffer.concat(chunks).includes(0x0a)) break;
+          }
+          return Buffer.concat(chunks).toString("utf8").trim();
+        });
+      value = await read(`Enter value for ${name}: `);
+    }
+    store.set(name, value);
+    await store.save?.();
+    write(`oke vault: set ${name}\n`);
+    return 0;
+  }
+
+  if (sub === "list") {
+    const names = store.names();
+    if (names.length === 0) {
+      write("oke vault: (empty)\n");
+      return 0;
+    }
+    for (const n of names) write(`${n}\n`);
+    return 0;
+  }
+
+  if (sub === "import") {
+    const file = rest[0];
+    if (!file) {
+      console.error("Usage: oke vault import <file>");
+      return 1;
+    }
+    const imported = await openEnvStore(resolve(cwd, file));
+    for (const n of imported.names()) {
+      const v = imported.get(n);
+      if (v !== undefined) store.set(n, v);
+    }
+    await store.save?.();
+    write(`oke vault: imported ${imported.names().length} key(s) from ${file}\n`);
+    return 0;
+  }
+
+  if (sub === "key" && rest[0] === "rotate") {
+    const buf = new Uint8Array(32);
+    crypto.getRandomValues(buf);
+    const key = Array.from(buf, (b) => b.toString(16).padStart(2, "0")).join("");
+    store.set("OKE_VAULT_KEY", key);
+    await store.save?.();
+    write("oke vault: rotated OKE_VAULT_KEY\n");
+    return 0;
+  }
+
+  console.error(`Unknown vault command: ${sub}`);
+  return 1;
+}

package/src/client/budget-entry.ts

@@ -0,0 +1,34 @@
+/**
+ * Bundle entry for the client size budget.
+ * Returns live bindings so minify cannot drop the runtime graph.
+ */
+
+import { createClient } from "./create.ts";
+import {
+  isErrorCode,
+  isFail,
+  isOk,
+  isTransportError,
+} from "./errors.ts";
+import { createTransport } from "./transport.ts";
+
+/**
+ * Anchor for the size check — must reference every runtime export.
+ */
+export function __okeClientBudgetAnchor(): {
+  createClient: typeof createClient;
+  createTransport: typeof createTransport;
+  isErrorCode: typeof isErrorCode;
+  isFail: typeof isFail;
+  isOk: typeof isOk;
+  isTransportError: typeof isTransportError;
+} {
+  return {
+    createClient,
+    createTransport,
+    isErrorCode,
+    isFail,
+    isOk,
+    isTransportError,
+  };
+}

package/src/client/budget.test.ts

@@ -0,0 +1,17 @@
+/**
+ * Client runtime budget — AGENTS.md / unified-theory §24.
+ * Limit: < 3 kB gzipped (minified bundle).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { CLIENT_BUDGET_BYTES } from "../release/limits.ts";
+import { measureClientGzipBytes } from "../release/measure.ts";
+
+describe("client bundle budget", () => {
+  test(`okengine/client < ${CLIENT_BUDGET_BYTES} bytes gzipped`, async () => {
+    const size = await measureClientGzipBytes();
+    console.log(`client bundle gzip=${size} budget=${CLIENT_BUDGET_BYTES}`);
+    expect(size).toBeGreaterThan(0);
+    expect(size).toBeLessThan(CLIENT_BUDGET_BYTES);
+  });
+});