create-oke 0.6.1 → 0.7.0

package/templates/standard/.env.example

@@ -0,0 +1,94 @@
+# Environment template — create-oke copies this to `.env.local` when you scaffold.
+#
+# Resolution order (first hit wins):
+#   process.env → .env.local → docker/.env.docker → vault driver → dev fallback
+#
+# --- Vault (app secrets) ---
+# Declare secrets in src/vault.ts with `vault.secret(...)`, then uncomment lines here.
+#
+# --- Infrastructure ---
+# Same keys as `docker/.env.docker` after `oke dev --docker`.
+# Uncomment to override compose credentials for a host-managed service.
+# Host ports under docker mode are unique per project — do not assume defaults.
+
+# ── App / Console ───────────────────────────────────────────
+# PORT=6530
+# OKE_APP_URL=http://127.0.0.1:6530
+# OKE_CONSOLE_SECRET=
+# MAINTENANCE_MODE=0
+# APP_WEBHOOK_SECRET=dev-webhook-secret-change-me
+
+# ── channel.email — Mailpit (SMTP + UI) ─────────────────────
+# OKE_CHANNEL_EMAIL_URL=smtp://127.0.0.1:1025
+# SMTP_URL=smtp://127.0.0.1:1025
+# SMTP_HOST=127.0.0.1
+# SMTP_PORT=1025
+# MAILPIT_UI_URL=http://127.0.0.1:8025
+# Optional controls:
+# SMTP_USER=
+# SMTP_PASSWORD=
+# MP_MAX_MESSAGES=500
+# MP_SMTP_AUTH_ACCEPT_ANY=1
+# MP_SMTP_AUTH_ALLOW_INSECURE=1
+
+# ── channel.email — HTTP providers ──────────────────────────
+# RESEND_API_KEY=
+# SNDR_API_KEY=
+# SNDR_BASE_URL=https://api.sndr.sh
+# SNDR_FROM=hello@your-verified-domain.com
+
+# ── channel.sms — Taqnyat / Msegat / Unifonic ───────────────
+# TAQNYAT_BEARER_TOKEN=
+# TAQNYAT_SENDER=
+# MSEGAT_USERNAME=
+# MSEGAT_API_KEY=
+# MSEGAT_SENDER=
+# UNIFONIC_APPSID=
+# UNIFONIC_SENDER=
+
+# ── channel.whatsapp / push ─────────────────────────────────
+# WHATSAPP_TOKEN=
+# WHATSAPP_PHONE_NUMBER_ID=
+# VAPID_PUBLIC_KEY=
+# VAPID_PRIVATE_KEY=
+# VAPID_SUBJECT=mailto:ops@example.com
+# FCM_PROJECT_ID=
+# FCM_CLIENT_EMAIL=
+# FCM_PRIVATE_KEY=
+
+# ── store.files — object storage (S3) ───────────────────────
+# OKE_STORE_FILES_URL=http://access-key:secret-key@127.0.0.1:9000/oke
+# S3_ACCESS_KEY_ID=access-key
+# S3_SECRET_ACCESS_KEY=secret-key
+# S3_BUCKET=oke
+# S3_URL=http://access-key:secret-key@127.0.0.1:9000/oke
+# S3_ENDPOINT=http://127.0.0.1:9000
+# S3_CONSOLE_URL=http://127.0.0.1:9001
+# S3_REGION=us-east-1
+# Optional controls:
+# S3_SESSION_TOKEN=
+
+# ── store.kv — Redis ────────────────────────────────────────
+# OKE_STORE_KV_PASSWORD=password
+# OKE_STORE_KV_URL=redis://:password@127.0.0.1:6379
+# REDIS_URL=redis://:password@127.0.0.1:6379
+# Optional controls:
+# OKE_STORE_KV_MAXMEMORY=256mb
+# OKE_STORE_KV_MAXMEMORY_POLICY=allkeys-lru
+
+# ── store.sql — Postgres ────────────────────────────────────
+# OKE_STORE_SQL_USER=oke
+# OKE_STORE_SQL_PASSWORD=password
+# OKE_STORE_SQL_DB=oke
+# OKE_STORE_SQL_URL=postgres://oke:password@127.0.0.1:5432/oke
+# DATABASE_URL=postgres://oke:password@127.0.0.1:5432/oke
+# Optional controls:
+# PGDATA=/var/lib/postgresql/data/pgdata
+# POSTGRES_INITDB_ARGS=--data-checksums
+
+# ── AI ──────────────────────────────────────────────────────
+# OKE_AI_DRIVER=ollama
+# OKE_AI_URL=http://127.0.0.1:11434
+# OKE_AI_MODEL=qwen3.5:9b
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=

package/templates/standard/README.md

@@ -0,0 +1,46 @@
+# Notes (standard)
+
+Local-first [okengine](https://oke.omqkhafi.dev) starter: a small **Notes** API with
+named Flows, Store, Signal → email, and Vault.
+
+```bash
+bun install
+oke dev
+```
+
+| Surface | URL |
+| ------- | --- |
+| App | http://127.0.0.1:6530 |
+| Console | http://127.0.0.1:6533 |
+| MCP | http://127.0.0.1:6535 |
+
+## Try it
+
+```bash
+curl -s http://127.0.0.1:6530/health
+curl -s -X POST http://127.0.0.1:6530/notes \
+  -H 'content-type: application/json' \
+  -d '{"title":"Hello","body":"First note"}'
+curl -s http://127.0.0.1:6530/notes
+```
+
+Flow names in the `oke dev` log are stable (`main.health`, `notes.create`, …) —
+never anonymous `flow_1`.
+
+## Layout
+
+| Path | Role |
+| ---- | ---- |
+| `src/schema.decl.ts` | `notes` table |
+| `src/flows/notes/` | list · create · get · archive · onCreated |
+| `src/flows/main/` | root · health |
+| `src/channels.ts` | `note-created` email template |
+| `src/vault.ts` | `APP_WEBHOOK_SECRET` |
+| `oke.config.ts` | local sqlite · docker postgres (+ redis/s3/openbao/smtp) |
+
+Switch mode anytime: `oke mode docker` then `oke dev` (or `oke dev --docker`).
+
+## AI
+
+Not baked into this starter. Re-run create-oke with `--ai`, or `oke ai setup`, to
+add `drivers.ai` + `src/ai.ts`.

package/templates/standard/drizzle.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "drizzle-kit";
+
+/**
+ * Domain schema sync for `oke db push|generate|migrate`.
+ *
+ * Dialect comes from OKE's `store.sql` driver map (resolved by the CLI and
+ * injected as `OKE_DRIZZLE_DIALECT`) — never inferred from `DATABASE_URL`
+ * presence. `src/schema.generated.ts` is emitted from `src/schema.decl.ts`
+ * for the active dialect as a pre-step of `oke db` / `oke dev`.
+ *
+ * Versioned prod migrations land in `./drizzle` — never mix with `.oke/`.
+ */
+const dialect = (process.env.OKE_DRIZZLE_DIALECT ?? "sqlite") as "sqlite" | "postgresql";
+
+export default defineConfig({
+  dialect,
+  schema: "./src/schema.generated.ts",
+  out: "./drizzle",
+  dbCredentials: {
+    url:
+      dialect === "postgresql"
+        ? (process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL!)
+        : (process.env.OKE_SQLITE_URL ?? "file:.oke/app.sqlite"),
+  },
+});

package/{template → templates/standard}/oke.config.ts

@@ -1,5 +1,9 @@
 import { defineConfig } from "okengine/config";
 
+/**
+ * Standard starter — local-first Notes.
+ * Docker/prod pins stay ready when you switch `oke mode docker`.
+ */
 export default defineConfig({
   drivers: {
     store: {
@@ -24,18 +28,18 @@ export default defineConfig({
     },
     signal: {
       local: "memory",
-      docker: "postgres",
+      docker: "redis",
       test: "memory",
-      prod: "postgres",
+      prod: "redis",
     },
     clock: {
       local: "memory",
-      docker: "postgres",
+      docker: "file",
       test: "frozen",
-      prod: "postgres",
+      prod: "file",
     },
     vault: {
-      local: "dotenv",
+      local: "env",
       docker: "openbao",
       test: "memory",
       prod: "openbao",
@@ -55,10 +59,6 @@ export default defineConfig({
     "store.files": "rustfs/rustfs:1.0.0-beta.11",
     "channel.email": "axllent/mailpit:v1.22.3",
     vault: "openbao/openbao:2.6.1",
-    // Opt in to full-text search (meilisearch store.index driver):
-    //   drivers.store.index: { local: "meilisearch", docker: "meilisearch", test: "memory", prod: "meilisearch" }
-    // and pin its image. Local mode then needs the `meilisearch` binary on PATH.
-    // "store.index": "getmeili/meilisearch:v1.37",
   },
   i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
 });

package/{template → templates/standard}/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "okengine": "file:../..",
+    "okengine": "file:../../../..",
     "drizzle-orm": "^1.0.0-rc.4",
     "zod": "^4.4.3"
   },

package/templates/standard/src/app.ts

@@ -0,0 +1,30 @@
+import { db } 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],
+  secrets: [webhookSecret],
+  signals: [noteCreated],
+  channel: { templates: [noteCreatedMail] },
+});

package/templates/standard/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/{template → templates/standard}/src/core.ts

@@ -1,4 +1,5 @@
 import { store } from "okengine";
 import * as schema from "./schema.decl";
 
+/** App SQL store — tables from {@link schema}. */
 export const db = store.sql("app", { schema });

package/templates/standard/src/flows/main/index.ts

@@ -0,0 +1,34 @@
+import { on, flow, http, gate } from "okengine";
+import { z } from "zod";
+
+/** 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(),
+    }),
+    do: () => ({
+      ok: true as const,
+      app: "notes",
+      try: ["GET /notes", "POST /notes", "GET /health"],
+      console: "http://127.0.0.1:6533",
+    }),
+  }),
+);
+
+/** 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/standard/src/flows/main/shapes.ts

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

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

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

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

@@ -0,0 +1,143 @@
+import { on, flow, http, gate, fail } from "okengine";
+import { eq, isNull } from "drizzle-orm";
+
+import { db } from "../../core";
+import { notes } from "../../schema.decl";
+import { webhookSecret } from "../../vault";
+import { noteCreatedMail } from "../../channels";
+import { NoteCreateIn, NoteIdIn, NoteListOut, NoteOut, 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 },
+      });
+    },
+  }),
+);

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

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

package/templates/standard/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/standard/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/standard/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/standard/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/standard/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/standard/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/standard/tests/standard.test.ts

@@ -0,0 +1,51 @@
+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 → list → archive", async () => {
+  const created = await t.api.notes.create({
+    title: "Hello",
+    body: "World from the standard starter",
+  });
+  expect(created.error).toBeNull();
+  expect(created.data?.title).toBe("Hello");
+  expect(created.data?.id).toBeTruthy();
+
+  await t.signals.drain();
+  expect(t.channels.sent().some((s) => s.template === "note-created")).toBe(true);
+
+  const listed = await t.api.notes.list({});
+  expect(listed.error).toBeNull();
+  expect(listed.data?.notes.some((n) => n.id === created.data!.id)).toBe(true);
+
+  const archived = await t.api.notes.archive({ id: created.data!.id });
+  expect(archived.error).toBeNull();
+  expect(archived.data?.archivedAt).toBeTypeOf("number");
+
+  const after = await t.api.notes.list({});
+  expect(after.data?.notes.some((n) => n.id === created.data!.id)).toBe(false);
+});
+
+/** Flag-free `app.fetch` must auto-boot. */
+test("bare fetch auto-boots the public health route", async () => {
+  const res = await app.fetch(new Request("http://localhost/health"));
+  expect(res.status).toBe(200);
+  expect(app.booted).toBe(true);
+  expect(await res.json()).toEqual({ data: { ok: true }, error: null });
+});