create-oke 0.6.1 → 0.7.0

package/templates/advanced/oke.config.ts

@@ -0,0 +1,74 @@
+import { defineConfig } from "okengine/config";
+
+/**
+ * Advanced starter — same Notes domain, docker-ready driver map.
+ * Recommended create path seeds `.oke/mode` as docker.
+ */
+export default defineConfig({
+  drivers: {
+    store: {
+      sql: {
+        local: "sqlite",
+        docker: "postgres",
+        test: "memory",
+        prod: "postgres",
+      },
+      kv: {
+        local: "memory",
+        docker: "redis",
+        test: "memory",
+        prod: "redis",
+      },
+      files: {
+        local: "fs",
+        docker: "s3",
+        test: "memory",
+        prod: "s3",
+      },
+      // Opt in via create-oke customize or uncomment:
+      // index: {
+      //   local: "memory",
+      //   docker: "meilisearch",
+      //   test: "memory",
+      //   prod: "meilisearch",
+      // },
+    },
+    signal: {
+      local: "memory",
+      docker: "redis",
+      test: "memory",
+      prod: "redis",
+    },
+    clock: {
+      local: "memory",
+      docker: "file",
+      test: "frozen",
+      prod: "file",
+    },
+    vault: {
+      local: "env",
+      docker: "openbao",
+      test: "memory",
+      prod: "openbao",
+    },
+    channel: {
+      email: {
+        local: "console",
+        docker: "smtp",
+        test: "console",
+        prod: "smtp",
+      },
+    },
+    // Opt in: create-oke --ai / oke ai setup writes drivers.ai + src/ai.ts
+  },
+  images: {
+    "store.sql": "postgres:18-alpine",
+    "store.kv": "redis:8-alpine",
+    "store.files": "rustfs/rustfs:1.0.0-beta.11",
+    "channel.email": "axllent/mailpit:v1.22.3",
+    vault: "openbao/openbao:2.6.1",
+    // "store.index": "getmeili/meilisearch:v1.37",
+    // ai: "ollama/ollama:latest",
+  },
+  i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
+});

package/templates/advanced/package.json

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

package/templates/advanced/src/app.ts

@@ -0,0 +1,30 @@
+import { db, files } from "./core";
+import "./gates";
+import "./vault";
+import "./channels";
+import "./locales/en";
+import "./locales/ar";
+
+import { oke } from "okengine";
+import * as main from "./flows/main";
+import * as notes from "./flows/notes";
+import { noteCreated } from "./flows/notes/signals";
+import { noteCreatedMail } from "./channels";
+import { webhookSecret } from "./vault";
+
+export const app = oke({
+  name: "notes",
+  secrets: [webhookSecret],
+  signals: [noteCreated],
+  channel: { templates: [noteCreatedMail] },
+}).adopt({ main, notes });
+
+export type App = typeof app;
+
+Object.assign(app.$options, {
+  env: "test",
+  stores: [db, files],
+  secrets: [webhookSecret],
+  signals: [noteCreated],
+  channel: { templates: [noteCreatedMail] },
+});

package/templates/advanced/src/channels.ts

@@ -0,0 +1,13 @@
+import { channel } from "okengine";
+import { z } from "zod";
+
+const mail = channel.email({ from: "Notes <notes@localhost>" });
+
+/** Email when a note is created (console driver locally · SMTP in docker). */
+export const noteCreatedMail = mail.template("note-created", {
+  locales: ["en", "ar"],
+  schema: z.object({
+    id: z.string(),
+    title: z.string(),
+  }),
+});

package/templates/advanced/src/core.ts

@@ -0,0 +1,8 @@
+import { store } from "okengine";
+import * as schema from "./schema.decl";
+
+/** App SQL store — tables from {@link schema}. */
+export const db = store.sql("app", { schema });
+
+/** Object storage for note attachments (fs locally · s3 in docker). */
+export const files = store.files("uploads");

package/{template → templates/advanced}/src/flows/main/index.ts

@@ -1,30 +1,33 @@
 import { on, flow, http, gate } from "okengine";
 import { z } from "zod";
 
-import "./shapes";
-import "./signals";
-
 /** First-run welcome — visit :6530/ after `oke dev`. */
 export const root = on(
   http.get("/").gate(gate.public),
   flow({
+    name: "main.root",
+    unit: "main",
     out: z.object({
       ok: z.literal(true),
+      app: z.string(),
+      try: z.array(z.string()),
       console: z.string(),
-      try: z.string(),
     }),
     do: () => ({
       ok: true as const,
+      app: "notes",
+      try: ["GET /notes", "POST /notes", "GET /health"],
       console: "http://127.0.0.1:6533",
-      try: "/health",
     }),
   }),
 );
 
-/** Replace with your unit's flows. */
+/** Liveness for probes and `bun test`. */
 export const health = on(
   http.get("/health").gate(gate.public),
   flow({
+    name: "main.health",
+    unit: "main",
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
   }),

package/templates/advanced/src/flows/main/shapes.ts

@@ -0,0 +1 @@
+/** Main-unit contracts — keep route-local shapes next to flows when they grow. */

package/templates/advanced/src/flows/main/signals.ts

@@ -0,0 +1 @@
+/** Main-unit signals — none in the standard starter. */

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

@@ -0,0 +1,224 @@
+import { on, flow, http, every, gate, fail } from "okengine";
+import { eq, isNull } from "drizzle-orm";
+
+import { db, files } from "../../core";
+import { notes } from "../../schema.decl";
+import { webhookSecret } from "../../vault";
+import { noteCreatedMail } from "../../channels";
+import {
+  NoteAttachIn,
+  NoteAttachOut,
+  NoteCreateIn,
+  NoteDigestOut,
+  NoteIdIn,
+  NoteListOut,
+  NoteOut,
+  NoteSummarizeIn,
+  NoteSummarizeOut,
+  NotFound,
+} from "./shapes";
+import { noteCreated } from "./signals";
+
+import "./shapes";
+import "./signals";
+
+/** List active (non-archived) notes, newest first. */
+export const list = on(
+  http.get("/notes").gate(gate.public),
+  flow({
+    name: "notes.list",
+    unit: "notes",
+    out: NoteListOut,
+    effects: { reads: ["sql:app"] },
+    do: async (_input, fx) => {
+      const rows = await fx.store(db).select().from(notes).where(isNull(notes.archivedAt));
+      const sorted = [...rows].sort((a, b) => Number(b.createdAt) - Number(a.createdAt));
+      return {
+        notes: sorted.map((r) => ({
+          id: String(r.id),
+          title: String(r.title),
+          body: String(r.body),
+          archivedAt: r.archivedAt == null ? null : Number(r.archivedAt),
+          createdAt: Number(r.createdAt),
+        })),
+      };
+    },
+  }),
+);
+
+/** Create a note, emit `note-created`, touch vault. */
+export const create = on(
+  http.post("/notes").gate(gate.public),
+  flow({
+    name: "notes.create",
+    unit: "notes",
+    in: NoteCreateIn,
+    out: NoteOut,
+    effects: {
+      writes: ["sql:app"],
+      emits: ["note-created"],
+      secrets: ["APP_WEBHOOK_SECRET"],
+    },
+    do: async (input, fx) => {
+      // Prove Vault is wired (local: env/dev fallback).
+      fx.vault(webhookSecret);
+      const id = fx.id();
+      const createdAt = fx.clock.now();
+      await fx.store(db).insert(notes).values({
+        id,
+        title: input.title,
+        body: input.body,
+        archivedAt: null,
+        createdAt,
+      });
+      await fx.emit(noteCreated, { id, title: input.title }, { key: id });
+      return {
+        id,
+        title: input.title,
+        body: input.body,
+        archivedAt: null,
+        createdAt,
+      };
+    },
+  }),
+);
+
+/** Fetch one note by id. */
+export const get = on(
+  http.get("/notes/:id").gate(gate.public),
+  flow({
+    name: "notes.get",
+    unit: "notes",
+    in: NoteIdIn,
+    out: NoteOut,
+    errors: { NotFound },
+    effects: { reads: ["sql:app"] },
+    do: async (input, fx) => {
+      const row = await fx.store(db).findById(notes, input.id);
+      if (!row) return fail("NotFound", { id: input.id });
+      return {
+        id: String(row.id),
+        title: String(row.title),
+        body: String(row.body),
+        archivedAt: row.archivedAt == null ? null : Number(row.archivedAt),
+        createdAt: Number(row.createdAt),
+      };
+    },
+  }),
+);
+
+/** Soft-archive a note. */
+export const archive = on(
+  http.post("/notes/:id/archive").gate(gate.public),
+  flow({
+    name: "notes.archive",
+    unit: "notes",
+    in: NoteIdIn,
+    out: NoteOut,
+    errors: { NotFound },
+    effects: { reads: ["sql:app"], writes: ["sql:app"] },
+    do: async (input, fx) => {
+      const row = await fx.store(db).findById(notes, input.id);
+      if (!row) return fail("NotFound", { id: input.id });
+      const archivedAt = fx.clock.now();
+      await fx
+        .store(db)
+        .update(notes)
+        .set({ archivedAt })
+        .where(eq(notes.id, input.id));
+      return {
+        id: String(row.id),
+        title: String(row.title),
+        body: String(row.body),
+        archivedAt,
+        createdAt: Number(row.createdAt),
+      };
+    },
+  }),
+);
+
+/** On create → send the note-created email template. */
+export const onCreated = on(
+  noteCreated,
+  flow({
+    name: "notes.onCreated",
+    unit: "notes",
+    effects: { sends: ["note-created"] },
+    do: async (payload, fx) => {
+      await fx.send(noteCreatedMail, {
+        to: "you@localhost",
+        data: { id: payload.id, title: payload.title },
+      });
+    },
+  }),
+);
+
+/** Store a text attachment next to a note (`files:uploads`). */
+export const attach = on(
+  http.post("/notes/:id/attach").gate(gate.public),
+  flow({
+    name: "notes.attach",
+    unit: "notes",
+    in: NoteAttachIn,
+    out: NoteAttachOut,
+    errors: { NotFound },
+    effects: { reads: ["sql:app"], writes: ["files:uploads"] },
+    do: async (input, fx) => {
+      const row = await fx.store(db).findById(notes, input.id);
+      if (!row) return fail("NotFound", { id: input.id });
+      const key = `notes/${input.id}/attachment.txt`;
+      await fx.store(files).put(key, input.text);
+      return { key, bytes: new TextEncoder().encode(input.text).byteLength };
+    },
+  }),
+);
+
+/** Daily count of active notes (frozen under test drivers). */
+export const digest = on(
+  every("1d"),
+  flow({
+    name: "notes.digest",
+    unit: "notes",
+    out: NoteDigestOut,
+    effects: { reads: ["sql:app"] },
+    do: async (_input, fx) => {
+      const rows = await fx.store(db).select().from(notes).where(isNull(notes.archivedAt));
+      return { active: rows.length, at: fx.clock.now() };
+    },
+  }),
+);
+
+/**
+ * Summarize a note via AI when configured (`oke ai setup` / create-oke --ai).
+ * Without an AI runtime, returns a local fallback excerpt.
+ */
+export const summarize = on(
+  http.post("/notes/:id/summarize").gate(gate.public),
+  flow({
+    name: "notes.summarize",
+    unit: "notes",
+    in: NoteSummarizeIn,
+    out: NoteSummarizeOut,
+    errors: { NotFound },
+    effects: { reads: ["sql:app"], asks: ["summarize-note"] },
+    do: async (input, fx) => {
+      const row = await fx.store(db).findById(notes, input.id);
+      if (!row) return fail("NotFound", { id: input.id });
+      const body = String(row.body);
+      try {
+        const out = await fx.ask("summarize-note", {
+          title: String(row.title),
+          body,
+        });
+        const summary =
+          typeof out === "object" && out !== null && "summary" in out
+            ? String((out as { summary: unknown }).summary)
+            : JSON.stringify(out);
+        return { id: input.id, summary, via: "ai" as const };
+      } catch {
+        const summary = body.length > 160 ? `${body.slice(0, 157)}…` : body;
+        return { id: input.id, summary, via: "fallback" as const };
+      }
+    },
+  }),
+);

package/templates/advanced/src/flows/notes/shapes.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+export const NoteCreateIn = z.object({
+  title: z.string().min(1).max(200),
+  body: z.string().min(1).max(10_000),
+});
+
+export const NoteOut = z.object({
+  id: z.string(),
+  title: z.string(),
+  body: z.string(),
+  archivedAt: z.number().nullable(),
+  createdAt: z.number(),
+});
+
+export const NoteListOut = z.object({
+  notes: z.array(NoteOut),
+});
+
+export const NoteIdIn = z.object({
+  id: z.string().min(1),
+});
+
+export const NotFound = z.object({
+  id: z.string(),
+});
+
+export const NoteAttachIn = z.object({
+  id: z.string().min(1),
+  /** UTF-8 text body stored under `notes/{id}/attachment.txt`. */
+  text: z.string().min(1).max(100_000),
+});
+
+export const NoteAttachOut = z.object({
+  key: z.string(),
+  bytes: z.number().int().nonnegative(),
+});
+
+export const NoteDigestOut = z.object({
+  active: z.number().int().nonnegative(),
+  at: z.number(),
+});
+
+export const NoteSummarizeIn = z.object({
+  id: z.string().min(1),
+});
+
+export const NoteSummarizeOut = z.object({
+  id: z.string(),
+  summary: z.string(),
+  via: z.enum(["ai", "fallback"]),
+});

package/templates/advanced/src/flows/notes/signals.ts

@@ -0,0 +1,13 @@
+import { signal } from "okengine";
+import { z } from "zod";
+
+/** Fired after a note is persisted — subscriber sends email. */
+export const noteCreated = signal("note-created", {
+  delivery: "once",
+  retries: 3,
+  deadLetter: true,
+  schema: z.object({
+    id: z.string(),
+    title: z.string(),
+  }),
+});

package/templates/advanced/src/gates.ts

@@ -0,0 +1,12 @@
+import { gate } from "okengine";
+
+/**
+ * Starter keeps HTTP public. Replace with real policies when you add auth:
+ *
+ * ```ts
+ * export const canWriteNotes = gate.policy("notes:write", ({ auth }) =>
+ *   auth.scopes.has("notes:write"),
+ * );
+ * ```
+ */
+export const notesWrite = gate.policy("notes:write", () => true);

package/templates/advanced/src/locales/ar.ts

@@ -0,0 +1,18 @@
+import { defineLocale } from "okengine";
+import type { MessagesFor } from "okengine";
+import type { en } from "./en";
+
+const ar = {
+  errors: {
+    notFound: "غير موجود",
+    unauthorized: "غير مصرح",
+  },
+  notes: {
+    created: "تم إنشاء الملاحظة «{title}».",
+    archived: "تم أرشفة الملاحظة.",
+    empty: "لا توجد ملاحظات نشطة بعد.",
+    count: "{count, plural, zero {لا ملاحظات} one {ملاحظة واحدة} two {ملاحظتان} few {# ملاحظات} many {# ملاحظة} other {# ملاحظة}}",
+  },
+} satisfies MessagesFor<typeof en>;
+
+defineLocale("ar", ar);

package/templates/advanced/src/locales/en.ts

@@ -0,0 +1,22 @@
+import { defineMessages, defineLocale } from "okengine";
+
+export const en = defineMessages({
+  errors: {
+    notFound: "Not found",
+    unauthorized: "Unauthorized",
+  },
+  notes: {
+    created: "Note “{title}” was created.",
+    archived: "Note archived.",
+    empty: "No active notes yet.",
+    count: "{count, plural, =0 {no notes} one {# note} other {# notes}}",
+  },
+});
+
+defineLocale("en", en);
+
+declare module "okengine" {
+  interface Register {
+    messages: typeof en;
+  }
+}

package/templates/advanced/src/schema.decl.ts

@@ -0,0 +1,13 @@
+import { store, field, id, now } from "okengine";
+
+/**
+ * Notes domain — abstract declarations, emitted to
+ * `src/schema.generated.ts` for the active dialect by `oke db` / `oke dev`.
+ */
+export const notes = store.schema.table("notes", {
+  id: field.text().primaryKey().defaultFn(id),
+  title: field.text().notNull(),
+  body: field.text().notNull(),
+  archivedAt: field.integer(),
+  createdAt: field.integer().notNull().defaultFn(now),
+});

package/templates/advanced/src/vault.ts

@@ -0,0 +1,7 @@
+import { vault } from "okengine";
+
+/** Shared webhook HMAC secret — prove Vault wiring on note create. */
+export const webhookSecret = vault.secret("APP_WEBHOOK_SECRET", {
+  description: "HMAC secret for outbound note webhooks",
+  dev: "dev-webhook-secret-change-me",
+});

package/templates/advanced/tests/advanced.test.ts

@@ -0,0 +1,42 @@
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import { createTestApp, type TestApp } from "okengine/test";
+import { app, type App } from "../src/app";
+
+let t: TestApp<App>;
+
+beforeAll(async () => {
+  t = await createTestApp(app);
+});
+
+afterAll(async () => {
+  await t.close();
+});
+
+test("boots — health flow is named main.health", async () => {
+  const { data, error } = await t.api.main.health({});
+  expect(error).toBeNull();
+  expect(data).toEqual({ ok: true });
+});
+
+test("notes create → attach → summarize fallback → archive", async () => {
+  const created = await t.api.notes.create({
+    title: "Advanced",
+    body: "Body long enough to exercise attach and summarize paths in the advanced starter.",
+  });
+  expect(created.error).toBeNull();
+  const id = created.data!.id;
+
+  await t.signals.drain();
+
+  const attached = await t.api.notes.attach({ id, text: "attachment body" });
+  expect(attached.error).toBeNull();
+  expect(attached.data?.key).toBe(`notes/${id}/attachment.txt`);
+
+  const summary = await t.api.notes.summarize({ id });
+  expect(summary.error).toBeNull();
+  expect(summary.data?.via).toBe("fallback");
+  expect(summary.data?.summary.length).toBeGreaterThan(0);
+
+  const archived = await t.api.notes.archive({ id });
+  expect(archived.error).toBeNull();
+});