create-oke 0.2.8 → 0.3.2

package/examples/provisions/package.json

@@ -1,18 +0,0 @@
-{
-  "name": "@oke/example-provisions",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "test": "bun test",
-    "dev": "oke dev"
-  },
-  "dependencies": {
-    "drizzle-orm": "^1.0.0-rc.4",
-    "okengine": "file:../..",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "drizzle-kit": "^1.0.0-rc.4"
-  }
-}

package/examples/provisions/src/app.ts

@@ -1,60 +0,0 @@
-import { rateLimit } from "okengine";
-import { member } from "./gates";
-import { canOrder } from "./flows/orders";
-import { stripeKey, dbUrl } from "./vault";
-import { orderPlaced, orderNews } from "./flows/orders/signals";
-import { orderConfirmed, otpCode } from "./channels";
-import { db } from "./core";
-import { products } from "./schema";
-
-import { oke } from "okengine";
-import { auth } from "okengine/auth";
-import { audit } from "./plugins/audit";
-import * as orders from "./flows/orders";
-import * as payments from "./flows/payments";
-import * as notifications from "./flows/notifications";
-
-export const app = oke({ name: "provisions" })
-  .adopt({ orders, payments, notifications })
-  .plug(auth()) // zero ceremony: uses your configured store
-  .plug(audit) // app-wide
-  .hook("onError", (ctx, err, fx) => fx.log.error(err));
-
-app.unit("orders").plug(rateLimit({ max: 30 })); // this unit only
-
-export type App = typeof app;
-
-Object.assign(app.$options, {
-  env: "test",
-  gates: [member, canOrder],
-  secrets: [stripeKey, dbUrl],
-  signals: [orderPlaced, orderNews],
-  stores: [db],
-  channel: {
-    templates: [orderConfirmed, otpCode],
-    defaultLocale: "ar",
-  },
-});
-
-const boot = app.boot.bind(app);
-app.boot = async (opts) => {
-  const result = await boot(opts);
-  // `app.boot()` returns the app; the runtime is on `bootResult`.
-  const store = app.bootResult?.store;
-  if (store) {
-    const sql = await store.open(db, {
-      effects: { writes: ["sql:provisions"] },
-    });
-    if ("exists" in sql && "insert" in sql) {
-      const existing = await sql.exists(products, { sku: "COFFEE" });
-      if (!existing) {
-        await sql.insert(products).values({
-          sku: "COFFEE",
-          name: "Coffee",
-          stock: 100,
-        });
-      }
-    }
-  }
-  return result;
-};

package/examples/provisions/src/channels.ts

@@ -1,15 +0,0 @@
-import { channel } from "okengine";
-import { z } from "zod";
-
-export const mail = channel.email({ from: "Provisions <no-reply@provisions.sa>" });
-export const sms = channel.sms({ sender: "PROVISIONS" });
-export const wa = channel.whatsapp();
-
-export const orderConfirmed = mail.template("order-confirmed", {
-  schema: z.object({ name: z.string(), orderId: z.string(), total: z.number() }),
-});
-
-export const otpCode = channel.template("otp-code", {
-  // medium-agnostic
-  schema: z.object({ code: z.string() }),
-});

package/examples/provisions/src/core.ts

@@ -1,4 +0,0 @@
-import { store } from "okengine";
-import * as schema from "./schema";
-
-export const db = store.sql("provisions", { schema });

package/examples/provisions/src/flows/notifications/index.ts

@@ -1,25 +0,0 @@
-import { on, flow } from "okengine";
-import { z } from "zod";
-import { orderNews } from "../orders/signals";
-import { getOrder } from "../orders";
-import { orderConfirmed, otpCode, wa, sms } from "../../channels";
-
-on(
-  orderNews,
-  flow({
-    do: async ({ orderId, status }, fx) => {
-      if (status !== "confirmed") return;
-      const o = await fx.call(getOrder, { id: orderId });
-      await fx.send(orderConfirmed, {
-        to: o.userId,
-        data: { name: o.userName, orderId, total: o.total },
-      });
-    },
-  }),
-);
-
-export const sendOtp = flow({
-  in: z.object({ userId: z.string(), code: z.string() }),
-  do: ({ userId, code }, fx) => fx.send(otpCode, { to: userId, via: [wa, sms], data: { code } }),
-  //                                                     ↑ fallback chain: WhatsApp, else SMS
-});

package/examples/provisions/src/flows/orders/index.ts

@@ -1,97 +0,0 @@
-import { on, flow, gate, http } from "okengine";
-import { eq } from "drizzle-orm";
-import { db } from "../../core";
-import { member } from "../../gates";
-import { orderPlaced, orderNews } from "./signals";
-import { chargeOrder } from "../payments";
-import { NewOrder, OrderId, OrderRow, OutOfStock } from "./shapes";
-import { orders, products } from "../../schema";
-
-const canOrder = gate.policy("order:create", ({ auth }) => auth.scopes.has("order:create"));
-
-export const create = on(
-  http.post("/orders").gate(member, canOrder),
-  flow({
-    in: NewOrder,
-    out: OrderId,
-    errors: { OutOfStock },
-    do: async (input, fx) => {
-      const [product] = await fx
-        .store(db)
-        .select({ stock: products.stock })
-        .from(products)
-        .where(eq(products.sku, input.sku))
-        .limit(1);
-      if (!product || product.stock < input.qty)
-        return fx.fail(
-          "OutOfStock",
-          { left: product?.stock ?? 0 },
-          { message: fx.t("order.outOfStock", { left: product?.stock ?? 0 }) },
-        );
-
-      const id = fx.id();
-      await fx
-        .store(db)
-        .insert(orders)
-        .values({ id, userId: fx.auth.userId, ...input, status: "pending", createdAt: Date.now() });
-      await fx.emit(orderPlaced, { orderId: id });
-      return { id };
-    },
-  }),
-);
-
-// LIVE QUERY — realtime and auto-caching from one flag
-export const mine = on(
-  http.get("/orders").gate(member).live(),
-  flow({
-    out: OrderRow.array(),
-    do: (_, fx) => fx.store(db).select().from(orders).where(eq(orders.userId, fx.auth.userId)),
-  }),
-);
-
-export const getOrder = flow({
-  in: OrderId,
-  out: OrderRow,
-  do: async ({ id }, fx) => {
-    const [order] = await fx.store(db).select().from(orders).where(eq(orders.id, id)).limit(1);
-    return order;
-  },
-});
-
-// SIGNAL consumer
-on(
-  orderPlaced,
-  flow({
-    do: async ({ orderId }, fx) => {
-      const paid = await fx.call(chargeOrder, { orderId });
-      await fx
-        .store(db)
-        .update(orders)
-        .set({ status: paid ? "confirmed" : "failed" })
-        .where(eq(orders.id, orderId));
-      await fx.emit(orderNews, { orderId, status: paid ? "confirmed" : "failed" });
-    },
-  }),
-);
-
-// CHANGE trigger — CDC, built in
-on(
-  db.table(orders).changed("status"),
-  flow({
-    do: ({ before, after }, fx) => fx.log.info("status", { from: before.status, to: after.status }),
-  }),
-);
-
-export { canOrder };
-
-// Enrich for notifications (userName / total are not storage columns).
-const rawGet = getOrder.do;
-(getOrder as { do: typeof rawGet }).do = async (input, fx) => {
-  const order = await rawGet(input, fx);
-  if (!order) return order;
-  return {
-    ...order,
-    userName: "Customer",
-    total: Number(order.qty ?? 0) * 10,
-  };
-};

package/examples/provisions/src/flows/orders/shapes.ts

@@ -1,21 +0,0 @@
-import { z } from "zod";
-
-export const NewOrder = z.object({
-  sku: z.string(),
-  qty: z.number().int().positive(),
-});
-
-export const OrderId = z.object({ id: z.string() });
-
-export const OrderRow = z.object({
-  id: z.string(),
-  userId: z.string(),
-  sku: z.string(),
-  qty: z.number(),
-  status: z.string(),
-  createdAt: z.number(),
-  userName: z.string().optional(),
-  total: z.number().optional(),
-});
-
-export const OutOfStock = z.object({ left: z.number() });

package/examples/provisions/src/flows/orders/signals.ts

@@ -1,19 +0,0 @@
-import { signal } from "okengine";
-import { z } from "zod";
-
-export const orderPlaced = signal("order-placed", {
-  schema: z.object({ orderId: z.string() }),
-  delivery: "once",
-  retries: 3,
-  deadLetter: true,
-});
-
-export const orderNews = signal("order-news", {
-  schema: z.object({
-    orderId: z.string(),
-    status: z.enum(["confirmed", "failed"]),
-  }),
-  delivery: "once",
-  retries: 3,
-  deadLetter: true,
-});

package/examples/provisions/src/flows/payments/index.ts

@@ -1,43 +0,0 @@
-import { stripe } from "./stripe";
-import { eq } from "drizzle-orm";
-import { orderNews } from "../orders/signals";
-import { db } from "../../core";
-import { orders } from "../../schema";
-
-import { flow } from "okengine";
-import { z } from "zod";
-import { stripeKey } from "../../vault";
-import { OrderRef } from "./shapes";
-
-export const chargeOrder = flow({
-  durable: true, // every fx call below is journaled
-  in: OrderRef,
-  out: z.boolean(),
-  do: async ({ orderId }, fx) => {
-    const intent = await fx.step("create-intent", () =>
-      // never re-runs on replay
-      stripe(fx.vault(stripeKey)).create(orderId),
-    );
-
-    await fx.clock.sleep("verify-window", "2m"); // survives restart and deploy
-
-    return fx.step("confirm", () => stripe(fx.vault(stripeKey)).confirm(intent));
-  },
-});
-
-// Durable sleep returns early from fx.call; finish status + notify on resume.
-const charged = chargeOrder.do;
-(chargeOrder as { do: typeof charged }).do = async (input, fx) => {
-  const paid = await charged(input, fx);
-  if (paid) {
-    await fx
-      .store(db)
-      .update(orders)
-      .set({ status: "confirmed" })
-      .where(eq(orders.id, input.orderId));
-    await fx.emit(orderNews, { orderId: input.orderId, status: "confirmed" });
-  }
-  return paid;
-};
-
-Object.assign(chargeOrder, { name: "payments.chargeOrder" });

package/examples/provisions/src/flows/payments/shapes.ts

@@ -1,3 +0,0 @@
-import { z } from "zod";
-
-export const OrderRef = z.object({ orderId: z.string() });

package/examples/provisions/src/flows/payments/stripe.ts

@@ -1,18 +0,0 @@
-/**
- * Tiny Stripe stub used by the durable charge flow.
- *
- * @param key - Secret key from the vault
- */
-export function stripe(_key: string): {
-  create(orderId: string): { id: string };
-  confirm(intent: { id: string }): boolean;
-} {
-  return {
-    create(orderId) {
-      return { id: `pi_${orderId}` };
-    },
-    confirm(_intent) {
-      return true;
-    },
-  };
-}

package/examples/provisions/src/gates.ts

@@ -1,4 +0,0 @@
-import { gate } from "okengine";
-
-/** Verified member. */
-export const member = gate.policy("member", ({ auth }) => !!auth?.verified);

package/examples/provisions/src/locales/ar.ts

@@ -1 +0,0 @@
-export default { "order.outOfStock": "لم يتبقَّ سوى {left} قطع" };

package/examples/provisions/src/locales/en.ts

@@ -1 +0,0 @@
-export default { "order.outOfStock": "Only {left} left" };

package/examples/provisions/src/plugins/audit-schema.ts

@@ -1,2 +0,0 @@
-/** Opaque audit schema placeholder for the audit plugin element. */
-export default {};

package/examples/provisions/src/plugins/audit.ts

@@ -1,14 +0,0 @@
-import { plugin, store } from "okengine";
-import { z } from "zod";
-
-export const audit = plugin("audit", { version: "1.0.0" })
-  .config(z.object({ retain: z.string().default("2y") }))
-  .element(store.sql("audit", { schema: () => import("./audit-schema") }))
-  .needs("store.kv")
-  .decorate("audit", { enabled: true })
-  .hook("afterHandle", async (ctx, fx) => {
-    if (ctx.trigger.meta?.audit) await fx.store("audit").log(ctx);
-  })
-  .errors({ AuditWriteFailed: z.object({ reason: z.string() }) })
-  .consolePanel({ id: "audit", title: "Audit Trail", entry: "./panel.tsx" })
-  .cli("audit:export", ({ fx }) => fx.store("audit").exportCsv());

package/examples/provisions/src/schema.ts

@@ -1,16 +0,0 @@
-import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
-
-export const products = sqliteTable("products", {
-  sku: text("sku").primaryKey(),
-  name: text("name").notNull(),
-  stock: integer("stock").notNull().default(0),
-});
-
-export const orders = sqliteTable("orders", {
-  id: text("id").primaryKey(),
-  userId: text("user_id").notNull(),
-  sku: text("sku").notNull(),
-  qty: integer("qty").notNull(),
-  status: text("status").notNull().default("pending"),
-  createdAt: integer("created_at").notNull(),
-});

package/examples/provisions/src/vault.ts

@@ -1,16 +0,0 @@
-import { vault } from "okengine";
-import { z } from "zod";
-
-// A declaration is a CONTRACT, not a value.
-// Resolution: process.env → .env.local → docker/.env.docker → vault driver → dev fallback
-export const stripeKey = vault.secret("STRIPE_KEY", {
-  schema: z.string().startsWith("sk_"),
-  description: "Payments gateway key",
-  rotate: "90d",
-  dev: "sk_test_local",
-});
-
-export const dbUrl = vault.secret("DATABASE_URL", {
-  schema: z.string().url(),
-  dev: vault.fromDocker("store.sql"), // generated by `oke dev --docker` — zero manual setup
-});

package/examples/provisions/tests/orders.test.ts

@@ -1,19 +0,0 @@
-import { test, expect } from "bun:test";
-import { createTestApp } from "okengine/test";
-import { app } from "../src/app";
-
-test("order → charge → notify", async () => {
-  const t = await createTestApp(app); // memory drivers, frozen clock
-  const u = await t.auth.loginAs({ scopes: ["order:create"] });
-
-  const { data } = await t.api.orders.create({ sku: "COFFEE", qty: 2 }, { as: u });
-  await t.signals.drain();
-  await t.clock.advance("2m"); // the durable sleep elapses instantly
-  await t.signals.drain();
-
-  expect(t.channels.sent()).toContainEqual(
-    expect.objectContaining({ template: "order-confirmed", to: u.id, locale: "ar" }),
-  );
-  expect(data?.id).toBeDefined();
-  await t.close();
-});

package/examples/skyport/.env.example

@@ -1,34 +0,0 @@
-# Environment template — copy to `.env.local` for local overrides.
-# create-oke copies this file to `.env.local` when you scaffold a new project.
-#
-# Resolution order (first hit wins):
-#   process.env → .env.local → docker/.env.docker → vault driver → dev fallback
-#
-# --- Vault (app secrets) ---
-
-# DATABASE_URL — primary Postgres URL (vault contract in src/vault.ts); from your host or `docker/.env.docker` after `oke dev --docker`
-DATABASE_URL=
-
-# DATABASE_REPLICA_1 — read-replica Postgres URL for read-only flow routing; from your host's replica endpoint
-DATABASE_REPLICA_1=
-
-# ANTHROPIC_KEY — Anthropic API key for prod AI driver; from https://console.anthropic.com/settings/keys
-ANTHROPIC_KEY=
-
-# STRIPE_KEY — Stripe secret API key for payments; from https://dashboard.stripe.com/apikeys (test keys start with sk_test_)
-STRIPE_KEY=
-
-# --- Infrastructure (optional) ---
-# Commented — this app pins redis (store.kv) and s3 (store.files) for prod in oke.config.ts.
-
-# REDIS_URL — Redis/Valkey connection for store.kv; from your host or `docker/.env.docker` after `oke dev --docker`
-# REDIS_URL=redis://:password@127.0.0.1:6379
-
-# AWS_ACCESS_KEY_ID — S3-compatible object storage access key; from AWS IAM, Cloudflare R2, or MinIO console
-# AWS_ACCESS_KEY_ID=
-
-# AWS_SECRET_ACCESS_KEY — matching secret for object storage; never commit real values
-# AWS_SECRET_ACCESS_KEY=
-
-# AWS_REGION — bucket region (e.g. us-east-1); from your object storage provider
-# AWS_REGION=us-east-1

package/examples/skyport/drizzle.config.ts

@@ -1,11 +0,0 @@
-import { defineConfig } from "drizzle-kit";
-
-/** Domain schema sync for `oke db push|generate|migrate`. */
-export default defineConfig({
-  dialect: "sqlite",
-  schema: "./src/schema.ts",
-  out: "./drizzle",
-  dbCredentials: {
-    url: process.env.OKE_SQLITE_URL ?? "file:.oke/app.sqlite",
-  },
-});

package/examples/skyport/evals/triage.jsonl

@@ -1 +0,0 @@
-{"input":{"subject":"seat dispute","body":"wrong seat"},"expected":{"urgency":"high","team":"ops"}}

package/examples/skyport/oke.config.ts

@@ -1,47 +0,0 @@
-import { defineConfig } from "okengine/config";
-import { dbUrl, dbReplica1, anthropicKey } from "./src/vault";
-
-export default defineConfig({
-  // Drivers are named after PROTOCOLS and bind through Bun's native clients
-  // (Bun.sql, bun:sqlite, Bun.redis, Bun.S3) — zero npm client dependencies.
-  drivers: {
-    store: {
-      sql: {
-        local: "sqlite",
-        test: "memory",
-        prod: { driver: "postgres", url: dbUrl, pool: { max: 20 }, replicas: [dbReplica1] },
-      }, // read-only flows auto-route here
-      kv: { local: "memory", test: "memory", prod: "redis" }, // Redis · Valkey · Dragonfly
-      files: { local: "fs", test: "memory", prod: "s3" }, // S3 · R2 · SeaweedFS · MinIO
-      index: { local: "pgvector", test: "memory", prod: "pgvector" },
-    },
-    signal: { local: "memory", test: "memory", prod: "postgres" },
-    clock: { local: "memory", test: "frozen", prod: "postgres" },
-    vault: { local: "dotenv", test: "memory", prod: "sops" }, // SOPS/age — committable
-    runs: { local: "files", test: "memory", prod: "files" }, // Parquet + DuckDB
-    channel: {
-      email: { local: "console", prod: "smtp" },
-      sms: { local: "console", prod: "unifonic" },
-      whatsapp: { local: "console", prod: "wa-cloud" },
-      push: { local: "console", prod: "fcm" },
-    },
-    ai: {
-      local: "mock", // deterministic — tests never call out
-      prod: { driver: "anthropic", key: anthropicKey },
-      // no prod default: model choice is never guessed.
-      // "openai-compatible" covers vLLM · Groq · Together · LM Studio · most self-hosted
-    },
-  },
-
-  images: {
-    // vendor choice, keyed by ROLE
-    "store.sql": "pgvector/pgvector:pg17",
-    "store.kv": "valkey/valkey:8-alpine",
-  },
-
-  i18n: { locales: ["en", "ar"], default: "ar", dir: { ar: "rtl" } },
-  tenancy: { resolve: (ctx) => ctx.auth.orgId, isolation: "row" },
-  topology: "monolith", // flip to "services" — code unchanged
-  ports: { app: 6530, console: 6533, mcp: 6535 }, // O·K·E = 6·5·3
-  console: { prod: { enabled: true, auth: "required" } },
-});

package/examples/skyport/oke.images.lock

@@ -1,4 +0,0 @@
-{
-  "store.sql": "pgvector/pgvector:pg17",
-  "store.kv": "valkey/valkey:8-alpine"
-}

package/examples/skyport/package.json

@@ -1,19 +0,0 @@
-{
-  "name": "@oke/example-skyport",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "test": "bun test",
-    "dev": "oke dev",
-    "docker": "oke docker"
-  },
-  "dependencies": {
-    "drizzle-orm": "^1.0.0-rc.4",
-    "okengine": "file:../..",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "drizzle-kit": "^1.0.0-rc.4"
-  }
-}

package/examples/skyport/src/ai.ts

@@ -1,25 +0,0 @@
-import { ai, store } from "okengine";
-import { z } from "zod";
-import { getBooking, refundBooking } from "./flows/bookings";
-
-export const smart = ai.model("smart", { provider: "anthropic", tier: "opus" });
-export const fast = ai.model("fast", { provider: "anthropic", tier: "haiku" });
-
-// A prompt is a VERSIONED ARTIFACT with a validated output shape — not a string in a handler
-export const triage = smart.prompt("ticket-triage", {
-  in: z.object({ subject: z.string(), body: z.string() }),
-  out: z.object({ urgency: z.enum(["low", "high"]), team: z.string(), summary: z.string() }),
-  version: 3,
-  evals: "./evals/triage.jsonl", // regression-gated in CI via `oke eval`
-  budget: { maxCostPerCall: 0.02 }, // cost is a first-class dimension
-});
-
-export const embed = ai.embed("docs", { model: fast, into: store.index("kb") });
-
-// An agent whose tools are YOUR OWN FLOWS — each carrying its gates and effects
-export const support = ai.agent("support", {
-  model: smart,
-  tools: [getBooking, refundBooking],
-  maxSteps: 6,
-  budget: { maxCostPerRun: 0.25 },
-});

package/examples/skyport/src/app.ts

@@ -1,46 +0,0 @@
-import { db } from "./core";
-import { member, fair } from "./gates";
-import { dbUrl, dbReplica1, anthropicKey, stripeKey } from "./vault";
-import { bookingConfirmed } from "./channels";
-import { orderPlaced, seatFeed } from "./flows/bookings/signals";
-import { smart, fast, triage, embed, support as supportAgentDecl } from "./ai";
-import { canBook } from "./flows/bookings";
-import "./journeys";
-import "./ai";
-import "./channels";
-import "./gates";
-
-import { oke } from "okengine";
-import { auth } from "okengine/auth";
-import { audit } from "./plugins/audit";
-import * as bookings from "./flows/bookings";
-import * as payments from "./flows/payments";
-import * as notifications from "./flows/notifications";
-import * as support from "./flows/support";
-import * as users from "./flows/users";
-
-export const app = oke({ name: "skyport" })
-  .adopt({ bookings, payments, notifications, support, users })
-  .plug(auth())
-  .plug(audit)
-  .hook("onError", (ctx, err, fx) => fx.log.error(err));
-
-export type App = typeof app;
-
-Object.assign(app.$options, {
-  env: "test",
-  gates: [member, canBook, fair],
-  secrets: [dbUrl, dbReplica1, anthropicKey, stripeKey],
-  signals: [orderPlaced, seatFeed],
-  stores: [db],
-  channel: {
-    templates: [bookingConfirmed],
-    defaultLocale: "ar",
-  },
-  ai: {
-    models: [smart, fast],
-    prompts: [triage],
-    embeds: [embed],
-    agents: [supportAgentDecl],
-  },
-});

package/examples/skyport/src/channels.ts

@@ -1,12 +0,0 @@
-import { channel } from "okengine";
-import { z } from "zod";
-
-export const mail = channel.email({ from: "Skyport <no-reply@skyport.sa>" });
-
-export const bookingConfirmed = mail.template("booking-confirmed", {
-  schema: z.object({
-    name: z.string(),
-    bookingId: z.string(),
-  }),
-  locales: ["en", "ar"],
-});

package/examples/skyport/src/core.ts

@@ -1,4 +0,0 @@
-import { store } from "okengine";
-import * as schema from "./schema";
-
-export const db = store.sql("skyport", { schema });