create-oke 0.11.2 → 0.13.0

package/templates/advanced/web/tsconfig.app.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "allowArbitraryExtensions": true,
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "include": ["src"]
+}

package/templates/advanced/web/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "files": [],
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+}

package/templates/advanced/web/tsconfig.node.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["bun"],
+    "skipLibCheck": true,
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

package/templates/advanced/web/vite.config.ts

@@ -0,0 +1,32 @@
+/**
+ * Vite 8 SPA for the Notes starter.
+ *
+ * `index.html` is the documented entry (not backend-integration HTML).
+ * The oke app stays on :6530. `server.proxy` keeps `createClient("")`
+ * same-origin — leave CORS at Vite's localhost default. `preview.proxy` inherits
+ * this map. Do not proxy `/` — `main.root` is `GET /` and would steal the SPA.
+ */
+
+import react from "@vitejs/plugin-react";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig, type ProxyOptions } from "vite";
+
+const root = dirname(fileURLToPath(import.meta.url));
+
+/** Local oke app (`oke dev`). */
+const APP_ORIGIN = "http://127.0.0.1:6530";
+
+const proxy: Record<string, ProxyOptions> = {
+  "/health": { target: APP_ORIGIN, changeOrigin: true },
+  "/notes": { target: APP_ORIGIN, changeOrigin: true },
+  "/_oke": { target: APP_ORIGIN, changeOrigin: true },
+};
+
+export default defineConfig({
+  root,
+  plugins: [react()],
+  // Load `VITE_*` from the app root (same place as `.env.example`).
+  envDir: resolve(root, ".."),
+  server: { proxy },
+});

package/templates/standard/.env.example

@@ -1,14 +1,15 @@
 # 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 driver → process.env → .env.local → dev fallback
 #
 # --- Vault (app secrets) ---
 # Declare secrets in src/vault.ts with `vault.secret(...)`, then uncomment lines here.
 #
 # ── vault — built-in encrypted-at-rest store ────────────────
 # `drivers.vault` is "vault": secrets live encrypted in Postgres, no extra service.
-# Nothing below is required to start — the dotenv layers above resolve first.
+# Nothing below is required to start — a value already in the vault backend wins
+# over leftover process.env / dotenv pins.
 #
 #   oke vault init                 # creates the store, prints the master key ONCE
 #   export OKE_VAULT_MASTER_KEY=…  # every later command / boot unseals with this
@@ -19,20 +20,27 @@
 # secret manager at boot. Committing it defeats encryption at rest.
 # OKE_VAULT_MASTER_KEY=
 #
-# For `drivers.vault: "managed"` instead, point at your provider secret store:
+# For `drivers.vault: "managed"` instead, point at an official provider:
+#   aws-secrets-manager · azure-key-vault · gcp-secret-manager · doppler · 1password
 # OKE_VAULT_PROVIDER=aws-secrets-manager
 # OKE_VAULT_REGION=us-east-1
-# Optional prefix for secret names (defaults to oke/<env>/):
+# Scope: AWS/Azure prefix, GCP project[/prefix], Doppler project/config, 1Password vault
 # OKE_VAULT_MOUNT=oke/prod/
+# Azure Key Vault URI / 1Password Connect host / optional Doppler origin:
+# OKE_VAULT_URL=
+# Doppler token / 1Password Connect token:
+# OKE_VAULT_TOKEN=
 #
 # --- Infrastructure ---
-# Same keys as `docker/.env.docker` after `oke dev --docker`.
+# Same keys `oke dev --docker` merges into `.env.local`.
 # 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
+# Vite web (`bun run web`): empty = same-origin proxy to oke dev
+# VITE_API_URL=
 # OKE_CONSOLE_SECRET=
 # MAINTENANCE_MODE=0
 # APP_WEBHOOK_SECRET=dev-webhook-secret-change-me

package/templates/standard/README.md

@@ -7,6 +7,7 @@ product — every Flow and table here is real wiring you keep or replace.
 ```bash
 bun install
 oke dev           # auto db push; asks once whether to seed
+bun run web       # Vite SPA — proxies /notes · /health to the app
 ```
 
 | Surface | URL |
@@ -14,6 +15,7 @@ oke dev           # auto db push; asks once whether to seed
 | Backend | http://127.0.0.1:6530 |
 | Console | http://127.0.0.1:6533 |
 | MCP | http://127.0.0.1:6535 |
+| Web | `bun run web` (Vite; API via proxy) |
 
 ## Try it
 
@@ -48,6 +50,7 @@ never anonymous `flow_1`.
 | `src/db/migrations/` | versioned drizzle migrations |
 | `src/flows/notes/` | list · create · get · archive · onCreated |
 | `src/flows/main/` | root · health |
+| `web/` | Vite 8 SPA — `createClient` + proxy to the app |
 | `oke.config.ts` | local env · docker postgres (+ redis/s3/smtp); vault built-in |
 | `.github/workflows/ci.yml` | `bun run typecheck` + `bun test` on push/PR |
 

package/templates/standard/oke.config.ts

@@ -22,12 +22,13 @@ export default defineConfig({
     store: {
       sql: "postgres:18-alpine",
       kv: "redis:8-alpine",
-      files: "rustfs/rustfs:1.0.0-beta.11",
+      files: "rustfs/rustfs:1.0.0-rc.2",
     },
     channel: {
-      email: "axllent/mailpit:v1.22.3",
+      email: "axllent/mailpit:v1.30.7",
     },
-    // pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51", // create-oke wizard / --pgdog
+    // pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.53", // create-oke wizard / --pgdog
+    // proxy: "caddy:2-alpine", // or traefik:v3.7 / nginx:1.31-alpine
   },
   i18n: { locales: ["en"], default: "en" },
 });

package/templates/standard/package.json

@@ -5,19 +5,30 @@
   "type": "module",
   "dependencies": {
     "okengine": "file:../../../..",
+    "@duckdb/node-api": "^1.5.5-r.2",
     "drizzle-orm": "1.0.0-rc.4",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4",
     "@electric-sql/pglite-pgvector": "^0.0.5",
     "@types/bun": "latest",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
     "drizzle-kit": "1.0.0-rc.4",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vite": "^8.2.0"
   },
+  "trustedDependencies": ["@duckdb/node-api"],
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -b -p web/tsconfig.json",
     "test": "oke test",
-    "dev": "oke dev"
+    "dev": "oke dev",
+    "web": "bunx --bun vite --config web/vite.config.ts",
+    "web:build": "tsc -b -p web/tsconfig.json && bunx --bun vite build --config web/vite.config.ts",
+    "web:preview": "bunx --bun vite preview --config web/vite.config.ts"
   }
 }

package/templates/standard/src/app.ts

@@ -1,8 +1,9 @@
 import "@/core";
+import { notesMutate } from "@/core";
 
 import { oke } from "okengine/http";
 import * as routes from "@/flows/generated";
 
-export const app = oke({ name: "notes" }).adopt(routes);
+export const app = oke({ name: "notes", gate: { policies: [notesMutate] } }).adopt(routes);
 
 export type App = typeof app;

package/templates/standard/src/core.ts

@@ -26,10 +26,22 @@ export const db = store.sql("app", { schema });
  * export const notesWrite = gate.policy("notes:write", ({ auth }) =>
  *   auth.scopes.has("notes:write"),
  * );
+ * export const notesMutate = gate.all(notesWrite, notesWriteRate);
  * ```
  */
 export const notesWrite = gate.policy("notes:write", () => true);
 
+/** Note write throttle. */
+export const notesWriteRate = gate.rate({
+  max: 60,
+  per: "1m",
+  keyBy: "ip",
+  description: "Note write throttle",
+});
+
+/** Reuse on every notes mutate route. */
+export const notesMutate = gate.all(notesWrite, notesWriteRate);
+
 // --- Vault -------------------------------------------------------------------
 
 /** HMAC secret for outbound note webhooks (`fx.vault.get` on create). */

package/templates/standard/src/db/seed/index.ts

@@ -50,6 +50,8 @@ async function sampleNotes(fx: Fx) {
 }
 
 export default defineSeed({
+  name: "notes",
+  description: "Welcome + sample notes",
   essential: welcomeNote,
   dev: sampleNotes,
   // prod: async (fx) => { /* real production-only data, e.g. register a webhook */ },

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

@@ -1,9 +1,9 @@
-import { on, flow, http, gate } from "okengine";
+import { on, flow, http } from "okengine";
 import { z } from "zod";
 
-/** First-run welcome — visit :6530/ after `oke dev`. */
+/** First-run welcome — visit :6530/ after `oke dev` (browser code block; curl stays JSON). */
 export const root = on(
-  http.get("/").gate(gate.public),
+  http.get("/").gate.public,
   flow("main.root", {
     out: z.object({
       ok: z.literal(true),
@@ -22,7 +22,7 @@ export const root = on(
 
 /** Liveness for probes and `bun test`. */
 export const health = on(
-  http.get("/health").gate(gate.public),
+  http.get("/health").gate.public,
   flow("main.health", {
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),

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

@@ -1,7 +1,7 @@
-import { on, flow, http, gate, fail } from "okengine";
+import { on, flow, http, fail } from "okengine";
 import { eq, isNull } from "drizzle-orm";
 
-import { db, noteCreatedMail, webhookSecret } from "@/core";
+import { db, noteCreatedMail, notesMutate, webhookSecret } from "@/core";
 import { notes } from "@/db/schema.decl";
 import { NoteCreateIn, NoteIdIn, NoteListOut, NoteOut, NotFound } from "./shapes";
 import { noteCreated } from "./signals";
@@ -11,28 +11,28 @@ import "./signals";
 
 /** List active (non-archived) notes, newest first. */
 export const list = on(
-  http.get("/notes").gate(gate.public),
+  http.get("/notes").gate.public,
   flow("notes.list", {
     out: NoteListOut,
-    do: async (_input, fx) => {
+    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) => ({
+      const data = [...rows]
+        .sort((a, b) => Number(b.createdAt) - Number(a.createdAt))
+        .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),
-        })),
-      };
+        }));
+      return fx.json.withQuery(data, input);
     },
   }),
 );
 
 /** Create a note, emit `note-created`, touch vault. */
 export const create = on(
-  http.post("/notes").gate(gate.public),
+  http.post("/notes").gate(notesMutate),
   flow("notes.create", {
     in: NoteCreateIn,
     out: NoteOut,
@@ -62,7 +62,7 @@ export const create = on(
 
 /** Fetch one note by id. */
 export const get = on(
-  http.get("/notes/:id").gate(gate.public),
+  http.get("/notes/:id").gate.public,
   flow("notes.get", {
     in: NoteIdIn,
     out: NoteOut,
@@ -83,7 +83,7 @@ export const get = on(
 
 /** Soft-archive a note. */
 export const archive = on(
-  http.post("/notes/:id/archive").gate(gate.public),
+  http.post("/notes/:id/archive").gate(notesMutate),
   flow("notes.archive", {
     in: NoteIdIn,
     out: NoteOut,

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

@@ -13,9 +13,8 @@ export const NoteOut = z.object({
   createdAt: z.number(),
 });
 
-export const NoteListOut = z.object({
-  notes: z.array(NoteOut),
-});
+/** List `data` is the item array. Pagination lives in HTTP `meta`. */
+export const NoteListOut = z.array(NoteOut);
 
 export const NoteIdIn = z.object({
   id: z.string().min(1),

package/templates/standard/tests/standard.test.ts

@@ -33,7 +33,8 @@ test("notes create → list → archive", async () => {
 
   const listed = await t.api.notes!.list!({});
   expect(listed.error).toBeNull();
-  const notes = (listed.data as { notes: { id: string }[] }).notes;
+  const notes = listed.data as { id: string }[];
+  expect(listed.meta).toMatchObject({ mode: "offset", offset: 0, next: null, prev: null });
   expect(notes.some((n) => n.id === row.id)).toBe(true);
 
   const archived = await t.api.notes!.archive!({ id: row.id });
@@ -41,7 +42,7 @@ test("notes create → list → archive", async () => {
   expect((archived.data as { archivedAt: number }).archivedAt).toBeTypeOf("number");
 
   const after = await t.api.notes!.list!({});
-  const afterNotes = (after.data as { notes: { id: string }[] }).notes;
+  const afterNotes = after.data as { id: string }[];
   expect(afterNotes.some((n) => n.id === row.id)).toBe(false);
 });
 

package/templates/standard/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Notes</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/standard/web/src/App.css

@@ -0,0 +1,78 @@
+.page {
+  max-width: 40rem;
+  margin: 0 auto;
+  padding: 2rem 1.25rem 4rem;
+}
+
+.head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.head h1 {
+  margin: 0;
+  font-size: 1.5rem;
+}
+
+.ok,
+.down {
+  margin: 0;
+  font-size: 0.875rem;
+}
+
+.ok {
+  color: #047857;
+}
+
+.down {
+  color: #b45309;
+}
+
+.compose {
+  display: grid;
+  gap: 0.5rem;
+  margin: 1.5rem 0;
+}
+
+.compose input,
+.compose textarea,
+.compose button,
+.list button {
+  font: inherit;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid #cbd5e1;
+  border-radius: 0.375rem;
+  background: #fff;
+}
+
+.compose button,
+.list button {
+  cursor: pointer;
+  width: fit-content;
+}
+
+.err {
+  color: #b91c1c;
+}
+
+.list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: grid;
+  gap: 0.75rem;
+}
+
+.list li {
+  display: flex;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.75rem 0;
+  border-top: 1px solid #e2e8f0;
+}
+
+.list p {
+  margin: 0.25rem 0 0;
+}

package/templates/standard/web/src/App.tsx

@@ -0,0 +1,100 @@
+import { useCallback, useEffect, useState, type FormEvent, type JSX } from "react";
+import { isOk } from "okengine/client";
+import { api, type Note } from "./client.ts";
+import "./App.css";
+
+/**
+ * Notes SPA — health + list + create + archive against the oke app.
+ */
+export function App(): JSX.Element {
+  const [health, setHealth] = useState<"unknown" | "ok" | "down">("unknown");
+  const [notes, setNotes] = useState<readonly Note[]>([]);
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [message, setMessage] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    const live = await api.main.health({});
+    setHealth(isOk(live) && live.data.ok ? "ok" : "down");
+    const listed = await api.notes.list({});
+    if (isOk(listed) && Array.isArray(listed.data)) {
+      setNotes(listed.data as readonly Note[]);
+      setMessage(null);
+      return;
+    }
+    setMessage(listed.error?.code ?? "notes.list failed");
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  async function onCreate(event: FormEvent<HTMLFormElement>): Promise<void> {
+    event.preventDefault();
+    const created = await api.notes.create({ title, body });
+    if (!isOk(created)) {
+      setMessage(created.error.code);
+      return;
+    }
+    setTitle("");
+    setBody("");
+    await refresh();
+  }
+
+  async function onArchive(id: string): Promise<void> {
+    const archived = await api.notes.archive({ id });
+    if (!isOk(archived)) {
+      setMessage(archived.error.code);
+      return;
+    }
+    await refresh();
+  }
+
+  return (
+    <main className="page">
+      <header className="head">
+        <h1>Notes</h1>
+        <p className={health === "ok" ? "ok" : "down"}>
+          {health === "unknown" ? "checking…" : health === "ok" ? "app up" : "app down — start oke dev"}
+        </p>
+      </header>
+
+      <form className="compose" onSubmit={(event) => void onCreate(event)}>
+        <input
+          name="title"
+          placeholder="Title"
+          value={title}
+          onChange={(event) => setTitle(event.target.value)}
+          required
+          maxLength={200}
+        />
+        <textarea
+          name="body"
+          placeholder="Body"
+          value={body}
+          onChange={(event) => setBody(event.target.value)}
+          required
+          maxLength={10_000}
+          rows={4}
+        />
+        <button type="submit">Create</button>
+      </form>
+
+      {message ? <p className="err">{message}</p> : null}
+
+      <ul className="list">
+        {notes.map((note) => (
+          <li key={note.id}>
+            <div>
+              <strong>{note.title}</strong>
+              <p>{note.body}</p>
+            </div>
+            <button type="button" onClick={() => void onArchive(note.id)}>
+              Archive
+            </button>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/templates/standard/web/src/client.ts

@@ -0,0 +1,38 @@
+/**
+ * Browser client — Vite proxies these paths to `oke dev` (:6530).
+ *
+ * `$routes` is passed at runtime so HTTP triggers use REST, not `/_oke` RPC.
+ * Do not import `src/app.ts` here — that graph is Bun/server-only.
+ */
+
+import { createClient } from "okengine/client";
+
+/** One note from `notes.list` / `notes.create`. */
+export type Note = {
+  readonly id: string;
+  readonly title: string;
+  readonly body: string;
+  readonly archivedAt: number | null;
+  readonly createdAt: number;
+};
+
+const $routes = {
+  main: {
+    health: { method: "GET", path: "/health" },
+  },
+  notes: {
+    list: { method: "GET", path: "/notes" },
+    create: { method: "POST", path: "/notes" },
+    get: { method: "GET", path: "/notes/:id" },
+    archive: { method: "POST", path: "/notes/:id/archive" },
+  },
+} as const;
+
+type AppRoutes = { readonly $routes: typeof $routes };
+
+/**
+ * Typed caller for starter Flows. `VITE_API_URL` is empty in dev (proxy).
+ */
+export const api = createClient<AppRoutes>(import.meta.env.VITE_API_URL ?? "", {
+  $routes,
+});

package/templates/standard/web/src/index.css

@@ -0,0 +1,18 @@
+:root {
+  color: #0f172a;
+  background: #f8fafc;
+  font-family: ui-sans-serif, system-ui, sans-serif;
+  line-height: 1.5;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+}
+
+#root {
+  min-height: 100vh;
+}

package/templates/standard/web/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.tsx";
+import "./index.css";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("web: #root missing");
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/standard/web/src/vite-env.d.ts

@@ -0,0 +1,17 @@
+interface ViteTypeOptions {
+  // By adding this line, you can make the type of ImportMetaEnv strict
+  // to disallow unknown keys.
+  // strictImportMetaEnv: unknown
+}
+
+interface ImportMetaEnv {
+  /**
+   * App origin for `createClient`. Unset / empty = same origin so Vite's
+   * `server.proxy` forwards `/notes` · `/health` · `/_oke` to `oke dev`.
+   */
+  readonly VITE_API_URL?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}