create-oke 0.1.4

package/src/transform.ts

@@ -0,0 +1,124 @@
+/**
+ * Rewrites applied when copying an `examples/<template>` tree into a new project.
+ *
+ * Exactly:
+ * 1. `package.json` `"name"` → the user-provided project name
+ * 2. `package.json` `"okengine": "file:../.."` → an installable reference
+ *    (absolute `file:<okengine-root>` in the monorepo; registry version otherwise)
+ * 3. Drop monorepo-only files that import paths outside the example tree
+ *    (today: `tests/docker.test.ts`)
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "./templates.ts";
+
+/** Shape of an example / scaffolded `package.json`. */
+export type ScaffoldPackageJson = {
+  name?: string;
+  version?: string;
+  private?: boolean;
+  type?: string;
+  dependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+  [key: string]: unknown;
+};
+
+/**
+ * Resolve the `okengine` dependency string written into the scaffolded package.json.
+ *
+ * - Monorepo / local: `file:<absolute-okengine-root>` (installable; not `file:../..`)
+ * - Published create-oke: the version of this package (kept in lockstep with okengine)
+ *
+ * @param localOkengineRoot - Absolute path when available
+ */
+export function resolveOkengineDependency(
+  localOkengineRoot: string | null,
+): string {
+  if (localOkengineRoot) return `file:${localOkengineRoot}`;
+  const pkgPath = join(packageRoot(), "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { version: string };
+  return pkg.version;
+}
+
+/**
+ * Rewrite an example `package.json` for a new project.
+ *
+ * @param source - Parsed example package.json
+ * @param projectName - npm package name for the new project
+ * @param okengineDep - Installable okengine dependency string
+ */
+export function transformPackageJson(
+  source: ScaffoldPackageJson,
+  projectName: string,
+  okengineDep: string,
+): ScaffoldPackageJson {
+  const dependencies = { ...source.dependencies };
+  if (dependencies["okengine"] !== undefined) {
+    dependencies["okengine"] = okengineDep;
+  }
+
+  return {
+    ...source,
+    name: projectName,
+    dependencies,
+  };
+}
+
+/**
+ * Whether a relative path inside a template should be omitted from the scaffold.
+ *
+ * Skips install/VCS artefacts and monorepo-only tests that import outside the
+ * example (e.g. skyport `tests/docker.test.ts` → `../../../src/cli/docker.ts`).
+ *
+ * @param relativePath - Path relative to the template root (`/`-separated)
+ */
+export function shouldSkipTemplatePath(relativePath: string): boolean {
+  const parts = relativePath.split(/[/\\]/);
+  if (parts.includes("node_modules") || parts.includes(".git")) return true;
+  const base = parts[parts.length - 1] ?? "";
+  if (
+    base === "bun.lock" ||
+    base === "bun.lockb" ||
+    base === "package-lock.json" ||
+    base === "yarn.lock" ||
+    base === "pnpm-lock.yaml"
+  ) {
+    return true;
+  }
+  // Monorepo CI fixture — not part of the four-applications app tree.
+  if (relativePath.replace(/\\/g, "/") === "tests/docker.test.ts") return true;
+  return false;
+}
+
+/**
+ * Sanitize a directory / package name for npm.
+ *
+ * @param raw - User-provided name
+ */
+export function sanitizeProjectName(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("create-oke: project name must not be empty");
+  }
+  // Allow scoped names; otherwise lowercase npm-safe slug.
+  if (trimmed.startsWith("@")) {
+    const m = /^(@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*)$/.exec(
+      trimmed,
+    );
+    if (!m) {
+      throw new Error(
+        `create-oke: invalid scoped package name "${trimmed}"`,
+      );
+    }
+    return trimmed;
+  }
+  const name = trimmed
+    .toLowerCase()
+    .replace(/[^a-z0-9._~-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!name || !/^[a-z0-9-~]/.test(name)) {
+    throw new Error(`create-oke: invalid project name "${raw}"`);
+  }
+  return name;
+}

package/templates/linkly/oke.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    store:  { sql: { dev: "sqlite", test: "memory", prod: "postgres" },
+              kv:  { dev: "memory", test: "memory", prod: "redis" } },
+    signal: { dev: "memory", test: "memory", prod: "postgres" },
+    clock:  { dev: "memory", test: "frozen", prod: "postgres" },
+  },
+});

package/templates/linkly/package.json

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

package/templates/linkly/src/app.ts

@@ -0,0 +1,21 @@
+import { db } from "./core";
+import { member, fair } from "./gates";
+import { linkClicked, linkStats } from "./flows/links/signals";
+
+import { oke } from "okengine";
+import * as links from "./flows/links";
+import * as analytics from "./flows/analytics";
+
+export const app = oke({ name: "linkly" }).adopt({ links, analytics });
+
+export type App = typeof app;
+
+// Spec test calls `t.api.links.report` though `report` lives in analytics.
+app.adopt({ links: { report: analytics.report } });
+
+Object.assign(app.$options, {
+  env: "test",
+  gates: [member, fair],
+  signals: [linkClicked, linkStats],
+  stores: [db],
+});

package/templates/linkly/src/core.ts

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

package/templates/linkly/src/flows/analytics/index.ts

@@ -0,0 +1,24 @@
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { eq, and } from "drizzle-orm";
+import { linkClicked } from "../links/signals";
+import { db } from "../../core";
+import { member } from "../../gates";
+import { daily } from "../../schema";
+
+on(linkClicked, flow({                    // a second consumer of the same signal
+  do: async ({ code, at }, fx) => {
+    const day = new Date(at).toISOString().slice(0, 10);
+    const [row] = await fx.store(db).select().from(daily)
+      .where(and(eq(daily.code, code), eq(daily.day, day))).limit(1);
+
+    if (row) await fx.store(db).increment(daily, row.id, "clicks");
+    else await fx.store(db).insert(daily).values({ id: fx.id(), code, day, clicks: 1 });
+  },
+}));
+
+export const report = on(http.get("/links/:code/report").gate(member), flow({
+  out: z.array(z.object({ day: z.string(), clicks: z.number() })),
+  do: ({ code }, fx) => fx.store(db).select({ day: daily.day, clicks: daily.clicks })
+    .from(daily).where(eq(daily.code, code)),
+}));

package/templates/linkly/src/flows/links/index.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { on, flow, http, every } from "okengine";
+import { eq, lt } from "drizzle-orm";
+import { db } from "../../core";
+import { member, fair } from "../../gates";
+import { linkClicked, linkStats } from "./signals";
+import { NewLink, LinkCode, Link, NotFound, Taken } from "./shapes";
+import { links } from "../../schema";
+
+// ① HTTP — "an endpoint"
+export const shorten = on(http.post("/links").gate(member, fair), flow({
+  in: NewLink, out: LinkCode, errors: { Taken },
+  do: async ({ url, code }, fx) => {
+    if (await fx.store(db).exists(links, { code })) return fx.fail("Taken", {});
+    const id = fx.id();
+    await fx.store(db).insert(links).values(
+      { id, code, url, userId: fx.auth.userId, clicks: 0, createdAt: Date.now() });
+    return { code };
+  },
+}));
+
+// ② HTTP — the hot path
+export const redirect = on(http.get("/:code").gate(fair), flow({
+  in: LinkCode, out: Link, errors: { NotFound },
+  do: async ({ code }, fx) => {
+    const [link] = await fx.store(db).select().from(links).where(eq(links.code, code)).limit(1);
+    if (!link) return fx.fail("NotFound", {});
+
+    await fx.emit(linkClicked, { code, at: Date.now() });   // same transaction as any write
+    return link;
+  },
+}));
+
+// ③ SIGNAL — "a queue consumer", and the same species as ① and ②
+on(linkClicked, flow({
+  do: async ({ code }, fx) => {
+    const [link] = await fx.store(db).select().from(links).where(eq(links.code, code)).limit(1);
+    const clicks = await fx.store(db).increment(links, link.id, "clicks");
+    await fx.emit(linkStats, { code, clicks });             // live: pushed to subscribers
+  },
+}));
+
+// ④ CLOCK — "a cron job", and still the same species
+on(every("1h"), flow({
+  do: (_, fx) => {
+    const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;   // 30 days
+    return fx.store(db).delete(links).where(lt(links.createdAt, cutoff));
+  },
+}));
+
+// ⑤ A plain flow with no trigger — callable, not "private"
+export const stats = flow({
+  in: LinkCode, out: z.object({ clicks: z.number() }),
+  do: async ({ code }, fx) => {
+    const [link] = await fx.store(db).select({ clicks: links.clicks })
+      .from(links).where(eq(links.code, code)).limit(1);
+    return link ?? { clicks: 0 };
+  },
+});

package/templates/linkly/src/flows/links/shapes.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+export const NewLink = z.object({
+  url: z.string().url(),
+  code: z.string().min(1).max(32),
+});
+
+export const LinkCode = z.object({
+  code: z.string(),
+});
+
+export const Link = z.object({
+  id: z.string(),
+  code: z.string(),
+  url: z.string(),
+  userId: z.string(),
+  clicks: z.number(),
+  createdAt: z.number(),
+});
+
+export const Taken = z.object({});
+export const NotFound = z.object({});

package/templates/linkly/src/flows/links/signals.ts

@@ -0,0 +1,13 @@
+import { signal } from "okengine";
+import { z } from "zod";
+
+export const linkClicked = signal("link-clicked", {
+  schema: z.object({ code: z.string(), at: z.number(), referrer: z.string().optional() }),
+  delivery: "once",                       // queue physics: one consumer, retries, DLQ
+  retries: 3, deadLetter: true,
+});
+
+export const linkStats = signal("link-stats", {
+  schema: z.object({ code: z.string(), clicks: z.number() }),
+  delivery: "live",                       // stream physics: clients subscribe
+});

package/templates/linkly/src/gates.ts

@@ -0,0 +1,8 @@
+import { gate } from "okengine";
+
+export const member = gate.policy("member", ({ auth }) => !!auth?.verified);
+
+export const fair = gate.rate({
+  strategy: "sliding-window-counter",   // near-exact, two keys, no boundary bursts
+  max: 60, per: "1m", keyBy: "ip",
+});

package/templates/linkly/src/schema.ts

@@ -0,0 +1,17 @@
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+export const links = sqliteTable("links", {
+  id:        text("id").primaryKey(),               // `increment` targets this column
+  code:      text("code").notNull().unique(),        // the short, human-facing key
+  url:       text("url").notNull(),
+  userId:    text("user_id").notNull(),
+  clicks:    integer("clicks").notNull().default(0),
+  createdAt: integer("created_at").notNull(),
+});
+
+export const daily = sqliteTable("daily", {
+  id:     text("id").primaryKey(),
+  code:   text("code").notNull(),
+  day:    text("day").notNull(),                      // "YYYY-MM-DD"
+  clicks: integer("clicks").notNull().default(0),
+});

package/templates/linkly/tests/linkly.test.ts

@@ -0,0 +1,19 @@
+import { test, expect } from "bun:test";
+import { createTestApp } from "okengine/test";
+import { app } from "../src/app";
+
+test("shorten → redirect → report · time travel", async () => {
+const t = await createTestApp(app);                 // memory drivers, frozen clock
+const u = await t.auth.loginAs({});
+
+await t.api.links.shorten({ url: "https://example.com", code: "sa" }, { as: u });
+await t.api.links.redirect({ code: "sa" });
+await t.signals.drain();                            // run queued work deterministically
+
+const { data } = await t.api.links.report({ code: "sa" }, { as: u });
+expect(data![0].clicks).toBe(1);
+
+await t.clock.advance("31d");
+await t.cron.run("1h");                             // time travel
+  await t.close();
+});

package/templates/notes/oke.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    store: { sql: { dev: "sqlite", test: "memory", prod: "postgres" } },
+  },
+});

package/templates/notes/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@oke/example-notes",
+  "version": "0.1.4",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "okengine": "file:../..",
+    "drizzle-orm": "^1.0.0-rc.4",
+    "drizzle-zod": "^0.8.3",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "test": "bun test",
+    "dev": "oke dev"
+  }
+}

package/templates/notes/src/app.ts

@@ -0,0 +1,13 @@
+import { db } from "./core";
+
+import { oke } from "okengine";
+import * as notes from "./flows/notes";
+
+export const app = oke({ name: "notes" }).adopt({ notes });
+
+export type App = typeof app;   // ← the client needs nothing else
+
+Object.assign(app.$options, {
+  env: "test",
+  stores: [db],
+});

package/templates/notes/src/core.ts

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

package/templates/notes/src/flows/notes/index.ts

@@ -0,0 +1,44 @@
+import { on, flow, http } from "okengine";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { z } from "zod";
+import { db } from "../../core";
+import { notes } from "../../schema";
+
+// Contracts derived from the schema — one source of truth, refined where the API is stricter
+const NewNote  = createInsertSchema(notes, { title: (s) => s.min(1).max(120) })
+                   .omit({ id: true, createdAt: true });
+const Note     = createSelectSchema(notes);
+const NoteId   = z.object({ id: z.string() });
+const NotFound = z.object({});
+
+export const create = on(http.post("/notes"), flow({
+  in: NewNote,
+  out: NoteId,
+  do: async (input, fx) => {
+    const [note] = await fx.store(db).insert(notes).values(input).returning();
+    return { id: note.id };
+  },
+}));
+// effects → writes[sql:notes]
+
+export const list = on(http.get("/notes"), flow({
+  out: Note.array(),
+  do: (_, fx) => fx.store(db).select().from(notes),
+}));
+// effects → reads[sql:notes]
+
+export const get = on(http.get("/notes/:id"), flow({
+  in: NoteId,
+  out: Note,
+  errors: { NotFound },
+  do: async ({ id }, fx) => (await fx.store(db).findById(notes, id)) ?? fx.fail("NotFound", {}),
+}));
+
+export const remove = on(http.delete("/notes/:id"), flow({
+  in: NoteId,
+  errors: { NotFound },
+  do: async ({ id }, fx) => {
+    const deleted = await fx.store(db).delete(notes, id);
+    if (!deleted) return fx.fail("NotFound", {});
+  },
+}));

package/templates/notes/src/schema.ts

@@ -0,0 +1,9 @@
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { id, now } from "okengine/store";
+
+export const notes = sqliteTable("notes", {
+  id:        text("id").primaryKey().$defaultFn(id),
+  title:     text("title").notNull(),
+  body:      text("body").notNull(),
+  createdAt: integer("created_at").notNull().$defaultFn(now),
+});

package/templates/notes/tests/notes.test.ts

@@ -0,0 +1,10 @@
+import { test, expect } from "bun:test";
+import { createTestApp } from "okengine/test";
+import { app } from "../src/app";
+
+test("create then read", async () => {
+  const t = await createTestApp(app);            // memory driver, automatic
+  const { data } = await t.api.notes.create({ title: "First", body: "Hello" });
+  const { data: note } = await t.api.notes.get({ id: data!.id });
+  expect(note!.title).toBe("First");
+});

package/templates/provisions/oke.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    store: { sql: { dev: "sqlite", test: "memory", prod: "postgres" },
+             kv:  { dev: "memory", test: "memory", prod: "redis" } },
+    signal: { dev: "memory", test: "memory", prod: "postgres" },
+    clock:  { dev: "memory", test: "frozen", prod: "postgres" },
+    vault:  { dev: "dotenv", test: "memory", prod: "sops" },
+    channel: {
+      email: { dev: "console", test: "console", prod: "smtp" },
+      sms: { dev: "console", test: "console", prod: "unifonic" },
+      whatsapp: { dev: "console", test: "console", prod: "wa-cloud" },
+    },
+  },
+  i18n: { locales: ["en", "ar"], default: "ar", dir: { ar: "rtl" } },
+});

package/templates/provisions/package.json

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

package/templates/provisions/src/app.ts

@@ -0,0 +1,60 @@
+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/templates/provisions/src/channels.ts

@@ -0,0 +1,14 @@
+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/templates/provisions/src/core.ts

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

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

@@ -0,0 +1,19 @@
+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
+});